C/the.ansi.c.programming.language/c.programming.notes/sx6c.html

   1 <!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
   2 <!-- This collection of hypertext pages is Copyright 1995-7 by Steve Summit. -->
   3 <!-- This material may be freely redistributed and used -->
   4 <!-- but may not be republished or sold without permission. -->
   5 <html>
   6 <head>
   7 <link rev="owner" href="mailto:scs@eskimo.com">
   8 <link rev="made" href="mailto:scs@eskimo.com">
   9 <title>6.3 Reading Lines</title>
  10 <link href="sx6b.html" rev=precedes>
  11 <link href="sx6d.html" rel=precedes>
  12 <link href="sx6.html" rev=subdocument>
  13 </head>
  14 <body>
  15 <H2>6.3 Reading Lines</H2>
  16
  17 <p>It's often convenient
  18 for a program to process its
  19 input not a character at a
  20 time but rather a line at a time, that is, to read an entire
  21 line of input and then act on it all at once.
  22 The standard C library has a couple of functions for reading lines,
  23 but they have a few awkward features,
  24 so we're going to learn more about character input (and about
  25 writing functions in general)
  26 by writing our own function to read one line.
  27 Here it is:
  28 <pre>
  29 #include &lt;stdio.h&gt;
  30
  31 /* Read one line from standard input, */
  32 /* copying it to line array (but no more than max chars). */
  33 /* Does not place terminating \n in line array. */
  34 /* Returns line length, or 0 for empty line, or EOF for end-of-file. */
  35
  36 int getline(char line[], int max)
  37 {
  38 int nch = 0;
  39 int c;
  40 max = max - 1;                  /* leave room for '\0' */
  41
  42 while((c = getchar()) != EOF)
  43         {
  44         if(c == '\n')
  45                 break;
  46
  47         if(nch &lt; max)
  48                 {
  49                 line[nch] = c;
  50                 nch = nch + 1;
  51                 }
  52         }
  53
  54 if(c == EOF &amp;&amp; nch == 0)
  55         return EOF;
  56
  57 line[nch] = '\0';
  58 return nch;
  59 }
  60 </pre>
  61 </p><p>As the comment indicates,
  62 this function will read one line of input from the standard input,
  63 placing it into the <TT>line</TT> array.
  64 The size of the <TT>line</TT> array is given by the <TT>max</TT> argument;
  65 the function will never write more than <TT>max</TT> characters into <TT>line</TT>.
  66 </p><p>The main body of the function is a <TT>getchar</TT> loop,
  67 much as we used in the character-copying program.
  68 In the body of this loop, however,
  69 we're storing the characters in an array
  70 (rather than immediately printing them out).
  71 Also, we're only reading one line of characters,
  72 then stopping and returning.
  73 </p><p>There are several new things to notice here.
  74 </p><p>First of all, the <TT>getline</TT> function accepts an array as a parameter.
  75 As we've said,
  76 array parameters are an exception to the rule that functions
  77 receive copies of their arguments--in
  78 the case of arrays, the function <em>does</em> have access to
  79 the actual array passed by the caller, and <em>can</em> modify it.
  80 Since the function is accessing the caller's array, not
  81 creating a new one to hold a copy, the function does not have
  82 to declare the argument array's size;
  83 it's set by the caller.
  84 (Thus, the brackets in ``<TT>char line[]</TT>'' are empty.)
  85
  86 However, so that we won't overflow the caller's array by
  87 reading too long a line into it,
  88 we allow the caller to pass along the size of the array,
  89 which we promise not to exceed.
  90 </p><p>Second, we see an example of the <TT>break</TT> statement.
  91 The top of the loop looks like our earlier character-copying loop--it
  92 stops when it reaches <TT>EOF</TT>--but
  93 we only want this loop to read one line, so we also stop
  94 (that is, break out of the loop) when we see the <TT>\n</TT>
  95 character signifying end-of-line.
  96 An equivalent loop, without the <TT>break</TT> statement, would be
  97 <pre>
  98         while((c = getchar()) != EOF &amp;&amp; c != '\n')
  99                 {
 100                 if(nch &lt; max)
 101                         {
 102                         line[nch] = c;
 103                         nch = nch + 1;
 104                         }
 105                 }
 106 </pre>
 107 </p><p>We haven't learned about the internal representation of strings yet,
 108
 109 but it turns out that strings in C are simply arrays of
 110 characters,
 111 which is why we are reading the line into an array of characters.
 112 The end of a string is marked by the special character, <TT>'\0'</TT>.
 113 To make sure that there's always room for that character,
 114 on our way in we
 115 subtract 1 from <TT>max</TT>, the argument that tells us how
 116 many characters we may place in the <TT>line</TT> array.
 117 When we're done reading the line,
 118 we store the end-of-string character <TT>'\0'</TT>
 119 at the end of the string we've just built in the <TT>line</TT> array.
 120 </p><p>Finally, there's one subtlety in the code which isn't too
 121 important for our purposes now but which you may wonder about:
 122 it's arranged to handle the possibility that a few characters
 123 (i.e. the apparent beginning of a line) are read,
 124 followed immediately by an <TT>EOF</TT>,
 125 without the usual <TT>\n</TT> end-of-line character.
 126 (That's why we return <TT>EOF</TT> only if we received <TT>EOF</TT>
 127 <em>and</em> we hadn't read any characters first.)
 128 </p><p>In any case, the function returns the length
 129 (number of characters) of the line it read,
 130 not including the <TT>\n</TT>.
 131 (Therefore, it returns 0 for an empty line.)
 132 Like <TT>getchar</TT>, it returns <TT>EOF</TT> when there are no more
 133 lines to read.
 134 (It happens that <TT>EOF</TT> is a negative number, so it will never
 135 match the length of a line that <TT>getline</TT> has read.)
 136 </p><p>Here is an example of a test program which calls
 137 <TT>getline</TT>,
 138 reading the input a line at a time and then printing
 139 each line back out:
 140 <pre>
 141 #include &lt;stdio.h&gt;
 142
 143 extern int getline(char [], int);
 144
 145 main()
 146 {
 147 char line[256];
 148
 149 while(getline(line, 256) != EOF)
 150         printf("you typed \"%s\"\n", line);
 151
 152 return 0;
 153 }
 154 </pre>
 155
 156 The notation <TT>char []</TT> in the function prototype for
 157 <TT>getline</TT> says that <TT>getline</TT> accepts as its
 158 first argument an array of <TT>char</TT>.
 159 When the program calls <TT>getline</TT>, it is careful to pass
 160 along the actual size of the array.
 161 (You might notice
 162 a potential problem:
 163 since the number 256 appears in two places,
 164 if we ever decide that 256 is too small,
 165 and that we want to be able to read longer lines,
 166 we could easily change one of the instances of 256,
 167 and forget to change the other one.
 168 Later we'll learn ways of solving--that is, avoiding--this
 169 sort of problem.)
 170 </p><hr>
 171 <p>
 172 Read sequentially:
 173 <a href="sx6b.html" rev=precedes>prev</a>
 174 <a href="sx6d.html" rel=precedes>next</a>
 175 <a href="sx6.html" rev=subdocument>up</a>
 176 <a href="top.html">top</a>
 177 </p>
 178 <p>
 179 This page by <a href="http://www.eskimo.com/~scs/">Steve Summit</a>
 180 // <a href="copyright.html">Copyright</a> 1995-1997
 181 // <a href="mailto:scs@eskimo.com">mail feedback</a>
 182 </p>
 183 </body>
 184 </html>