The Standard C++ Iostream Library

This page is a brief overview of the C++ <iostream> and <iomanip> libraries. In addition to documenting what should be available (according to Stroustrup), this page attempts to document the existing state of the default implementation libraries used with g++ 2.95.2. They don't always match.

Standard streams

Several streams are automatically declared in <iostream>. These include (with their types)
istream cin;
Standard input stream.
ostream cout;
Standard buffered output stream.
ostream cerr;
Standard unbuffered output stream for error messages.
ostream clog;
Standard buffered output stream for error messages.

To support the work being done on wide characters for internationalization, there are wide streams as well:

wistream wcin;
Standard input stream.
wostream wcout;
Standard buffered output stream.
wostream wcerr;
Standard unbuffered output stream for error messages.
wostream wclog;
Standard buffered output stream for error messages.

g++ 2.95.2

Wide streams are not implemented.

Output Functions

These methods and functions are for ostreams.

ostream& operator << (short n);

This is an example of the basic output operator. Similar methods exist for int, long, unsigned short, unsigned int, unsigned long, float, double, and long double. Because these routines return an output stream, these operations are chainable. For example,
      
      int a, b, c;
      float d, e;
      
      cout << a << d << b << e;
    

ostream& operator << (bool n);

Prints out a boolean value. false and true are printed out as 0 and 1 by default. If the formatting flag boolalpha from <iomanip> is placed on the stream, then true is printed out as the string true or whatever variant is appropriate for the locale. Same for false The manipulator noboolalpha returns boolean printing back to numeric values.

g++ 2.95.2

The formatting flags boolalpha and noboolalpha are not available. All bools are printed as 1 or 0.

ostream& operator << (const void * p);

This method writes out a pointer value.

ostream& put(char c);

Print a character;

ostream& write(const char * p, streamsize n);

Print n characters from the array pointed to by p.

ostream& operator << (char);

Print a character.

ostream& operator << (const char *);

Print a character array / string.

Input Functions

These methods and functions are for istreams.

istream& operator >> (short& n);

This is an example of the basic input operator. Similar methods exist for int, long, unsigned short, unsigned int, unsigned long, float, double, and long double. Because these routines return an input stream, these operations are chainable.

All of these routines skip over any leading white space, and finish when encountering white space after legal characters corresponding to their input type.

istream& operator >> (short& n);

Reads a boolean value, which should be either a 1 or a 0.

istream& operator >> (char& c);

Reads a character. Unlike the corresponding scanf("%c", &c) in <cstdio>, this routine removes all white space before reading a single non-space character.

istream& operator >> (char * s);

Reads a string.

istream::width(int n)

Restricts the immediately following string input on the istream to n-1 characters and a terminating null character. Any other characters are left on the stream for the next input. The width() member function of istreams has no effect when preceding input of any other variable type than string.

Additional Character and String Input

As mentioned before, the input operators for characters and strings remove leading white space. However, there are methods that allow input of characters that treat white space as characters.

get(char&)

Reads a single character from the stream into the argument given.

get(char * buf, int n)

Reads a line into a buffer of n characters. A null termination character is always written, so at most only n-1 characters are actually read from the stream. A newline character terminates input for this function. The newline character is not placed into the buffer, nor is it removed from the stream.

get(char *buf, int n, ch term)

Same as above, except that the character that terminates the input is explicitly specified.

getline(char *buf, int n)

Reads a line into a buffer of n characters. A null termination character is always written, so at most only n-1 characters from the stream are placed in the buffer. A newline character terminates input for this function. However, the newline character is removed from the stream. The newline character is not placed in the buffer.

getline(char *buf, int n, ch term)

Same as above, except that the character that terminates the input is explicitly specified. The input termination character is removed from the stream but not placed in the buffer.

read(char *buf, int n)

Reads at most n characters from the input stream and places them in the buffer. No terminating null character is placed in the buffer. There is no input termination character.

operator void * () const

This function allows the istream to be tested for errors. It returns a non-zero value if the next input is expected to succeed. Useful for error checking in loops. For example:
      while(cin){
        cin >> d;
        // Process here
        ...
      }
    

bool operator !() const;

Returns true if the stream is in a failed state.

Formatting

Formatting with iostreams is performed by setting flags in the stream class. There are often multiple ways of setting a particular flag.

The flags come in two types. The first type represents options that are either on or off. For example the uppercase flag is either on or off. The second type of flag represents a small set (more than 2) of options, of which only one at a time may be set. For example, the justification can be set to one of left justified, right justified, or internally justified.

All flags can be set using the setf() member function. The on/off type flags can be turned off using the unsetf member function. The small-set-option flags are changed using setf.

The setf function has two forms, one with one argument, one with two arguments. The first takes a logically or'ed combination of on/off flags. The second is used exclusively for setting the one-of-small-set flags. The first argument is the flag to be set, the second argument specifies which field of arguments the first flag belongs to.

All flags and fields belong to the class ios, which is included in all input and output streams. Consequently, they are accessed by using ios::name_of_flag or ios::name_of_field.

Base

The numeric base used to print integers can be set using the dec (base 10), oct (base 8), or hex (base 16) flags. These flags belong to the basefield field. Which ever one of these flags is set remains in effect until one of the others is set. By default, the dec flag is initially set for every stream.

For example the fragment

         cout.setf(ios::hex, ios::basefield);
         cout << 1234;
      
will print out the base 16 result of 4d2.

Justification

All types can be left right or internally justified within their fields. Left and right justification do the obvious thing. Internal justification is used only with numerical values and places the sign of the number in the leftmost column of the field while right justifying the rest of the number. Internal justification is occasionally used in accounting software.

All justification flags belong to the adjustfield field. The chosen adjustment remains in effect until another adjustment is chosen. By default, all streams are initially right justified.

IO Manipulators

Many of the iostream flags can be set/unset through the use of IO manipulators which are placed directly on the stream.

dec, oct, and hex manipulators

These manipulators can be placed directly on the stream. For example
      cout << hex << 1234;
    
will print out the base 16 result of 4d2.