Reading strings
---------------

   Use these methods to read strings (for example, a line at a time)
from the input stream:

 - Method: istream& istream::get (char* C, int LEN [, char DELIM])
     Read a string from the input stream, into the array at C.

     The remaining arguments limit how much to read: up to `len-1'
     characters, or up to (but not including) the first occurrence in
     the input of a particular delimiter character DELIM--newline
     (`\n') by default.  (Naturally, if the stream reaches end of file
     first, that too will terminate reading.)

     If DELIM was present in the input, it remains available as if
     unread; to discard it instead, see `iostream::getline'.

     `get' writes `\0' at the end of the string, regardless of which
     condition terminates the read.

 - Method: istream& istream::get (streambuf& SB [, char DELIM])
     Read characters from the input stream and copy them on the
     `streambuf' object SB.  Copying ends either just before the next
     instance of the delimiter character DELIM (newline `\n' by
     default), or when either stream ends.   If DELIM was present in
     the input, it remains available as if unread.

 - Method: istream& istream::getline (CHARPTR, int LEN [, char DELIM])
     Read a line from the input stream, into the array at CHARPTR.
     CHARPTR may be any of three kinds of pointer: `char*', `unsigned
     char*', or `signed char*'.

     The remaining arguments limit how much to read: up to (but not
     including) the first occurrence in the input of a line delimiter
     character DELIM--newline (`\n') by default, or up to `len-1'
     characters (or to end of file, if that happens sooner).

     If `getline' succeeds in reading a "full line", it also discards
     the trailing delimiter character from the input stream.  (To
     preserve it as available input, see the similar form of
     `iostream::get'.)

     If DELIM was *not* found before LEN characters or end of file,
     `getline' sets the `ios::fail' flag, as well as the `ios::eof'
     flag if appropriate.

     `getline' writes a null character at the end of the string,
     regardless of which condition terminates the read.

 - Method: istream& istream::read (POINTER, int LEN)
     Read LEN bytes into the location at POINTER, unless the input ends
     first.

     POINTER may be of type `char*', `void*', `unsigned char*', or
     `signed char*'.

     If the `istream' ends before reading LEN bytes, `read' sets the
     `ios::fail' flag.

 - Method: istream& istream::gets (char **S [, char DELIM])
     A GNU extension, to read an arbitrarily long string from the
     current input position to the next instance of the DELIM character
     (newline `\n' by default).

     To permit reading a string of arbitrary length, `gets' allocates
     whatever memory is required.  Notice that the first argument S is
     an address to record a character pointer, rather than the pointer
     itself.

 - Method: istream& istream::scan (const char *format ...)
     A GNU extension, similar to `fscanf(FILE, FORMAT, ...)'.  The
     FORMAT is a `scanf'-style format control string, which is used to
     read the variables in the remainder of the argument list from the
     `istream'.

 - Method: istream& istream::vscan (const char *format, va_list args)
     Like `istream::scan', but takes a single `va_list' argument.