The GNU C++ Iostream Library

3.3: Managing input streams: class istream

Class istream objects are specialized for input; as for ostream, they are derived from ios, so you can use any of the general-purpose methods from that base class. Declarations for this class also come from iostream.h.

3.3.1: Constructors

Constructor:  istream::istream ()

When used without arguments, the istream constructor simply allocates a new ios object and initializes the input counter (the value reported by istream::gcount) to 0.

Constructor:  istream::istream (streambuf *sb [, ostream tie])

You can also call the constructor with one or two arguments. The first argument sb is a streambuf*; if you supply this pointer, the constructor uses that streambuf for input. You can use the second optional argument tie to specify a related output stream as the initial value for ios::tie.

If you give the istream a streambuf explicitly, using this constructor, the sb is not destroyed (or deleted or closed) when the ostream is destroyed.

3.3.2: Reading one character

Use these methods to read a single character from the input stream:

Method:  int istream::get ()

Read a single character (or EOF) from the input stream, returning it (coerced to an unsigned char) as the result.

Method:  istream& istream::get (char& c)

Read a single character from the input stream, into &c.

Method:  int istream::peek ()

Return the next available input character, but without changing the current input position.

3.3.3: 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.

3.3.4: Repositioning an istream

Use these methods to control the current input position:

Method:  streampos istream::tellg ()

Return the current read position, so that you can save it and return to it later with istream::seekg.

Method:  istream& istream::seekg (streampos p)

Reset the input pointer (if the input device permits it) to p, usually the result of an earlier call to istream::tellg.

Method:  istream& istream::seekg (streamoff offset, ios::seek_dir ref)

Reset the input pointer (if the input device permits it) to offset characters from the beginning of the input, the current position, or the end of input. Specify how to interpret offset with one of these values for the second argument:

ios::beg

Interpret loc as an absolute offset from the beginning of the file.

ios::cur

Interpret loc as an offset relative to the current output position.

ios::end

Interpret loc as an offset from the current end of the output stream.

3.3.5: Miscellaneous istream utilities

Use these methods for housekeeping on istream objects:

Method:  int istream::gcount ()

Report how many characters were read from this istream in the last unformatted input operation.

Method:  int istream::ipfx (int keepwhite)

Ensure that the istream object is ready for reading; check for errors and end of file and flush any tied stream. ipfx skips whitespace if you specify 0 as the keepwhite argument, and ios::skipws is set for this stream.

To avoid skipping whitespace (regardless of the skipws setting on the stream), use 1 as the argument.

Call istream::ipfx to simplify writing your own methods for reading istream objects.

Method:  void istream::isfx ()

A placeholder for compliance with the draft ANSI standard; this method does nothing whatever.

If you wish to write portable standard-conforming code on istream objects, call isfx after any operation that reads from an istream; if istream::ipfx has any special effects that must be cancelled when done, istream::isfx will cancel them.

Method:  istream& istream::ignore ([int n] [, int delim])

Discard some number of characters pending input. The first optional argument n specifies how many characters to skip. The second optional argument delim specifies a ``boundary'' character: ignore returns immediately if this character appears in the input.

By default, delim is EOF; that is, if you do not specify a second argument, only the count n restricts how much to ignore (while input is still available).

If you do not specify how many characters to ignore, ignore returns after discarding only one character.

Method:  istream& istream::putback (char ch)

Attempts to back up one character, replacing the character backed-up over by ch. Returns EOF if this is not allowed. Putting back the most recently read character is always allowed. (This method corresponds to the C function ungetc.)

Method:  istream& istream::unget ()

Attempt to back up one character.