The GNU C++ Iostream Library - 3. Stream Classes

Go to the first, previous, next, last section, table of contents.

# 3. Stream Classes

The previous chapter referred in passing to the classes `ostream` and `istream`, for output and input respectively. These classes share certain properties, captured in their base class `ios`.

## 3.1 Shared properties: class `ios`

The base class `ios` provides methods to test and manage the state of input or output streams.

`ios` delegates the job of actually reading and writing bytes to the abstract class `streambuf`, which is designed to provide buffered streams (compatible with C, in the GNU implementation). See section 5. Using the `streambuf` Layer, for information on the facilities available at the `streambuf` level.

Constructor: ios::ios ([streambuf* sb [, ostream* tie])
  The `ios` constructor by default initializes a new `ios`, and if you supply a `streambuf` sb to associate with it, sets the state `good` in the new `ios` object. It also sets the default properties of the new object.

  You can also supply an optional second argument tie to the constructor: if present, it is an initial value for `ios::tie`, to associate the new `ios` object with another stream.

Destructor: ios::~ios ()
  The `ios` destructor is virtual, permitting application-specific behavior when a stream is closed--typically, the destructor frees any storage associated with the stream and releases any other associated objects.

### 3.1.1 Checking the state of a stream

Use this collection of methods to test for (or signal) errors and other exceptional conditions of streams:

Method: ios::operator void* () const
  You can do a quick check on the state of the most recent operation on a stream by examining a pointer to the stream itself. The pointer is arbitrary except for its truth value; it is true if no failures have occurred (`ios::fail` is not true). For example, you might ask for input on `cin` only if all prior output operations succeeded:

      if (cout)
      {
        // Everything OK so far
        cin >> new_value;
        ...
      }

Method: ios::operator ! () const
  In case it is more convenient to check whether something has failed, the operator `!` returns true if `ios::fail` is true (an operation has failed). For example, you might issue an error message if input failed:

      if (!cin)
      {
        // Oops
        cerr << "Eh?\n";
      }

Method: iostate ios::rdstate () const
  Return the state flags for this stream. The value is from the enumeration `iostate`. You can test for any combination of
  `goodbit`
    There are no indications of exceptional states on this stream.
  `eofbit`
    End of file.
  `failbit`
    An operation has failed on this stream; this usually indicates bad format of input.
  `badbit`
    The stream is unusable.

Method: void ios::setstate (iostate state)
  Set the state flag for this stream to state in addition to any state flags already set. Synonym (for upward compatibility): `ios::set`.

  See `ios::clear` to set the stream state without regard to existing state flags. See `ios::good`, `ios::eof`, `ios::fail`, and `ios::bad`, to test the state.

Method: int ios::good () const
  Test the state flags associated with this stream; true if no error indicators are set.

Method: int ios::bad () const
  Test whether a stream is marked as unusable. (Whether `ios::badbit` is set.)

Method: int ios::eof () const
  True if end of file was reached on this stream. (If `ios::eofbit` is set.)

Method: int ios::fail () const
  Test for any kind of failure on this stream: either some operation failed, or the stream is marked as bad. (If either `ios::failbit` or `ios::badbit` is set.)

Method: void ios::clear (iostate state)
  Set the state indication for this stream to the argument state. You may call `ios::clear` with no argument, in which case the state is set to `good` (no errors pending).

  See `ios::good`, `ios::eof`, `ios::fail`, and `ios::bad`, to test the state; see `ios::set` or `ios::setstate` for an alternative way of setting the state.

### 3.1.2 Choices in formatting

These methods control (or report on) settings for some details of controlling streams, primarily to do with formatting output:

Method: char ios::fill () const
  Report on the padding character in use.

Method: char ios::fill (char padding)
  Set the padding character. You can also use the manipulator `setfill`. See section 3.1.3 Changing stream properties using manipulators.

  Default: blank.

Method: int ios::precision () const
  Report the number of significant digits currently in use for output of floating point numbers.

  Default: `6`.

Method: int ios::precision (int signif)
  Set the number of significant digits (for input and output numeric conversions) to signif.

  You can also use the manipulator `setprecision` for this purpose. See section 3.1.3 Changing stream properties using manipulators.

Method: int ios::width () const
  Report the current output field width setting (the number of characters to write on the next ``<<'` output operation).

  Default: `0`, which means to use as many characters as necessary.

Method: int ios::width (int num)
  Set the input field width setting to num. Return the previous value for this stream.

  This value resets to zero (the default) every time you use ``<<'`; it is essentially an additional implicit argument to that operator. You can also use the manipulator `setw` for this purpose. See section 3.1.3 Changing stream properties using manipulators.

Method: fmtflags ios::flags () const
  Return the current value of the complete collection of flags controlling the format state. These are the flags and their meanings when set:
  `ios::dec`
  `ios::oct`
  `ios::hex`
    What numeric base to use in converting integers from internal to display representation, or vice versa: decimal, octal, or hexadecimal, respectively. (You can change the base using the manipulator `setbase`, or any of the manipulators `dec`, `oct`, or `hex`; see section 3.1.3 Changing stream properties using manipulators.) On input, if none of these flags is set, read numeric constants according to the prefix: decimal if no prefix (or a ``.'` suffix), octal if a ``0'` prefix is present, hexadecimal if a ``0x'` prefix is present. Default: `dec`.
  `ios::fixed`
    Avoid scientific notation, and always show a fixed number of digits after the decimal point, according to the output precision in effect. Use `ios::precision` to set precision.
  `ios::left`
  `ios::right`
  `ios::internal`
    Where output is to appear in a fixed-width field; left-justified, right-justified, or with padding in the middle (e.g. between a numeric sign and the associated value), respectively.
  `ios::scientific`
    Use scientific (exponential) notation to display numbers.
  `ios::showbase`
    Display the conventional prefix as a visual indicator of the conversion base: no prefix for decimal, ``0'` for octal, ``0x'` for hexadecimal.
  `ios::showpoint`
    Display a decimal point and trailing zeros after it to fill out numeric fields, even when redundant.
  `ios::showpos`
    Display a positive sign on display of positive numbers.
  `ios::skipws`
    Skip white space. (On by default).
  `ios::stdio`
    Flush the C `stdio` streams `stdout` and `stderr` after each output operation (for programs that mix C and C++ output conventions).
  `ios::unitbuf`
    Flush after each output operation.
  `ios::uppercase`
    Use upper-case characters for the non-numeral elements in numeric displays; for instance, ``0X7A'` rather than ``0x7a'`, or ``3.14E+09'` rather than ``3.14e+09'`.

Method: fmtflags ios::flags (fmtflags value)
  Set value as the complete collection of flags controlling the format state. The flag values are described under ``ios::flags ()'`.

  Use `ios::setf` or `ios::unsetf` to change one property at a time.

Method: fmtflags ios::setf (fmtflags flag)
  Set one particular flag (of those described for ``ios::flags ()'`; return the complete collection of flags previously in effect. (Use `ios::unsetf` to cancel.)

Method: fmtflags ios::setf (fmtflags flag, fmtflags mask)
  Clear the flag values indicated by mask, then set any of them that are also in flag. (Flag values are described for ``ios::flags ()'`.) Return the complete collection of flags previously in effect. (See `ios::unsetf` for another way of clearing flags.)

Method: fmtflags ios::unsetf (fmtflags flag)
  Make certain flag (a combination of flag values described for ``ios::flags ()'`) is not set for this stream; converse of `ios::setf`. Returns the old values of those flags.

### 3.1.3 Changing stream properties using manipulators

For convenience, manipulators provide a way to change certain properties of streams, or otherwise affect them, in the middle of expressions involving ``<<'` or ``>>'`. For example, you might write

    cout << "|" << setfill('*') << setw(5) << 234 << "|";

to produce ``|**234|'` as output.

Manipulator: ws
  Skip whitespace.

Manipulator: flush
  Flush an output stream. For example, ``cout << ... <<flush;'` has the same effect as ``cout << ...; cout.flush();'`.

Manipulator: endl
  Write an end of line character ``\n'`, then flushes the output stream.

Manipulator: ends
  Write ``\0'` (the string terminator character).

Manipulator: setprecision (int signif)
  You can change the value of `ios::precision` in ``<<'` expressions with the manipulator ``setprecision(signif)'`; for example,

      cout << setprecision(2) << 4.567;

  prints ``4.6'`. Requires ``#include <iomanip.h>'`.

Manipulator: setw (int n)
  You can change the value of `ios::width` in ``<<'` expressions with the manipulator ``setw(n)'`; for example,

      cout << setw(5) << 234;

  prints `` 234'` with two leading blanks. Requires ``#include <iomanip.h>'`.

Manipulator: setbase (int base)
  Where base is one of `10` (decimal), `8` (octal), or `16` (hexadecimal), change the base value for numeric representations. Requires ``#include <iomanip.h>'`.

Manipulator: dec
  Select decimal base; equivalent to ``setbase(10)'`.

Manipulator: hex
  Select hexadecimal base; equivalent to ``setbase(16)'`.

Manipulator: oct
  Select octal base; equivalent to ``setbase(8)'`.

Manipulator: setfill (char padding)
  Set the padding character, in the same way as `ios::fill`. Requires ``#include <iomanip.h>'`.

### 3.1.4 Extended data fields

A related collection of methods allows you to extend this collection of flags and parameters for your own applications, without risk of conflict between them:

Method: static fmtflags ios::bitalloc ()
  Reserve a bit (the single bit on in the result) to use as a flag. Using `bitalloc` guards against conflict between two packages that use `ios` objects for different purposes.

  This method is available for upward compatibility, but is not in the ANSI working paper. The number of bits available is limited; a return value of `0` means no bit is available.

Method: static int ios::xalloc ()
  Reserve space for a long integer or pointer parameter. The result is a unique nonnegative integer. You can use it as an index to `ios::iword` or `ios::pword`. Use `xalloc` to arrange for arbitrary special-purpose data in your `ios` objects, without risk of conflict between packages designed for different purposes.

Method: long& ios::iword (int index)
  Return a reference to arbitrary data, of long integer type, stored in an `ios` instance. index, conventionally returned from `ios::xalloc`, identifies what particular data you need.

Method: long ios::iword (int index) const
  Return the actual value of a long integer stored in an `ios`.

Method: void*& ios::pword (int index)
  Return a reference to an arbitrary pointer, stored in an `ios` instance. index, originally returned from `ios::xalloc`, identifies what particular pointer you need.

Method: void* ios::pword (int index) const
  Return the actual value of a pointer stored in an `ios`.

### 3.1.5 Synchronizing related streams

You can use these methods to synchronize related streams with one another:

Method: ostream* ios::tie () const
  Report on what output stream, if any, is to be flushed before accessing this one. A pointer value of `0` means no stream is tied.

Method: ostream* ios::tie (ostream* assoc)
  Declare that output stream assoc must be flushed before accessing this stream.

Method: int ios::sync_with_stdio ([int switch])
  Unless iostreams and C `stdio` are designed to work together, you may have to choose between efficient C++ streams output and output compatible with C `stdio`. Use ``ios::sync_with_stdio()'` to select C compatibility.

  The argument switch is a GNU extension; use `0` as the argument to choose output that is not necessarily compatible with C `stdio`. The default value for switch is `1`.

  If you install the `stdio` implementation that comes with GNU `libio`, there are compatible input/output facilities for both C and C++. In that situation, this method is unnecessary--but you may still want to write programs that call it, for portability.

### 3.1.6 Reaching the underlying `streambuf`

Finally, you can use this method to access the underlying object:

Method: streambuf* ios::rdbuf () const
  Return a pointer to the `streambuf` object that underlies this `ios`.

## 3.2 Managing output streams: class `ostream`

Objects of class `ostream` inherit the generic methods from `ios`, and in addition have the following methods available. Declarations for this class come from ``iostream.h'`.

Constructor: ostream::ostream ()
  The simplest form of the constructor for an `ostream` simply allocates a new `ios` object.

Constructor: ostream::ostream (streambuf* sb [, ostream tie])
  This alternative constructor requires a first argument sb of type `streambuf*`, to use an existing open stream for output. It also accepts an optional second argument tie, to specify a related `ostream*` as the initial value for `ios::tie`.

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

### 3.2.1 Writing on an `ostream`

These methods write on an `ostream` (you may also use the operator `<<`; see section 2. Operators and Default Streams).

Method: ostream& ostream::put (char c)
  Write the single character c.

Method: ostream& ostream::write (string, int length)
  Write length characters of a string to this `ostream`, beginning at the pointer string.

  string may have any of these types: `char*`, `unsigned char*`, `signed char*`.

Method: ostream& ostream::form (const char *format, ...)
  A GNU extension, similar to `fprintf(file, format, ...)`.

  format is a `printf`-style format control string, which is used to format the (variable number of) arguments, printing the result on this `ostream`. See `ostream::vform` for a version that uses an argument list rather than a variable number of arguments.

Method: ostream& ostream::vform (const char *format, va_list args)
  A GNU extension, similar to `vfprintf(file, format, args)`.

  format is a `printf`-style format control string, which is used to format the argument list args, printing the result on this `ostream`. See `ostream::form` for a version that uses a variable number of arguments rather than an argument list.

### 3.2.2 Repositioning an `ostream`

You can control the output position (on output streams that actually support positions, typically files) with these methods:

Method: streampos ostream::tellp ()
  Return the current write position in the stream.

Method: ostream& ostream::seekp (streampos loc)
  Reset the output position to loc (which is usually the result of a previous call to `ostream::tellp`). loc specifies an absolute position in the output stream.

Method: ostream& ostream::seekp (streamoff loc, rel)
  Reset the output position to loc, relative to the beginning, end, or current output position in the stream, as indicated by rel (a value from the enumeration `ios::seekdir`):
  `beg`
    Interpret loc as an absolute offset from the beginning of the file.
  `cur`
    Interpret loc as an offset relative to the current output position.
  `end`
    Interpret loc as an offset from the current end of the output stream.

### 3.2.3 Miscellaneous `ostream` utilities

You may need to use these `ostream` methods for housekeeping:

Method: ostream& flush ()
  Deliver any pending buffered output for this `ostream`.

Method: int ostream::opfx ()
  `opfx` is a prefix method for operations on `ostream` objects; it is designed to be called before any further processing. See `ostream::osfx` for the converse.

  `opfx` tests that the stream is in state `good`, and if so flushes any stream tied to this one.

  The result is `1` when `opfx` succeeds; else (if the stream state is not `good`), the result is `0`.

Method: void ostream::osfx ()
  `osfx` is a suffix method for operations on `ostream` objects; it is designed to be called at the conclusion of any processing. All the `ostream` methods end by calling `osfx`. See `ostream::opfx` for the converse.

  If the `unitbuf` flag is set for this stream, `osfx` flushes any buffered output for it.

  If the `stdio` flag is set for this stream, `osfx` flushes any output buffered for the C output streams ``stdout'` and ``stderr'`.

## 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'`.

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.1 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.2 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.3 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.4 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.

## 3.4 Input and output together: class `iostream`

If you need to use the same stream for input and output, you can use an object of the class `iostream`, which is derived from both `istream` and `ostream`.

The constructors for `iostream` behave just like the constructors for `istream`.

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

Constructor: iostream::iostream (streambuf* sb [, ostream* tie])
  You can also call a 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 and output.

  You can use the optional second argument tie (an `ostream*`) to specify a related output stream as the initial value for `ios::tie`.

As for `ostream` and `istream`, `iostream` simply uses the `ios` destructor. However, an `iostream` is not deleted by its destructor.

You can use all the `istream`, `ostream`, and `ios` methods with an `iostream` object.

Go to the first, previous, next, last section, table of contents.