Standard streams reference

Introduction

The C++ libraries provide the ability to perform input and output using streams. A "stream" is a sequence of characters read or written from an I/O device or file. C++ provides three standard streams:

The standard input stream (cin),
The standard output stream (cout), and
The standard error streams (cerr) and (clog).

On UNIX, these streams correspond to the standard input, standard output and standard error buffered stream I/O interfaces. Unless the user redirects these streams on the shell command line, the standard input provides characters that are typed by the user on the keyboard and the standard output and standard error streams display characters written to those streams by the program. A user can redirect those streams on the command line, effectively connecting them to a file or pipe. Pipes let a user make a chain of commands. The following UNIX command:

    grep int *.cpp | more

uses grep to search for all occurences of the string "int" in all of the C++ source files in the current directory and displays them page by page via more.

In order to use the standard input and output streams in C++, your program must include the definition of those streams. It does that by including the C++ library named iostream into the program:

    #include <iostream>
    using namespace std ;

Later versions of the GNU C++ compiler require an additional statement (as shown) to use the namespace std. Using this namespace makes the names of the standard streams, their functions, etc. available to the program.

Standard output stream

Let's discuss the standard output stream, cout, first. You can use this stream for displaying information. The C++ library defines the stream insertion operator, <<. It points from the value to be displayed to where the value will be displayed:

    #include <iostream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      int value ;
      value = 123 ;
      cout << value ;
    }

In the example program above, the integer value 123 will be written to the standard output stream, cout. The internal two's complement representation of 123 is converted to a string and is displayed.

The insertion operator, <<, can handle the conversion and display of any built-in C++ datatype. (The insertion operator is built with a powerful, and sometimes dangerous to use, C++ feature called "operator overloading.") This flexibility means that you don't have to think too hard about how to format simple values for display -- you just need to send the values to the standard output stream. In addition, multiple values can be written at once by cascading insertion operators. For example, the statement cout << value ; could be replaced by:

    cout << "The value is " << value << '.' << endl ;

which displays the line:

    The value is 123.

In this example, a string, an integer and a character value are all converted as needed and written to the standard output stream. The name endl is a format manipulator that inserts an end-of-line into the output stream to terminate the line. C++ provides a rich set of format manipulators to conrol how values are formatted for output. The table below lists some of the format manipulators available.

`dec`	Use decimal representation for integer input or output
`hex`	Use hexadecimal (base 16) representation for integer input or output
`octal`	Use octal (base 8) representation for integer input or output
`flush`	Flush the output stream
`endl`	Insert a newline character into the output stream and flush the stream
`left`	Left justify output
`right`	Right justify output

The integer value in our simple example can be shown in decimal and hexadecimal representation using the statement:

    cout << dec << value << " " << hex << value << endl ;

Give the other format manipulators a try!

Standard error stream

By convention, the standard error stream is used to display diagnostic or error messages. The standard error streams cerr and clog behave like the standard output stream cout. Output to clog is buffered while output to cerr is not. Thus, output to cerr is immediate while output to clog waits until the internal output buffer is full before physical output is initiated.

Standard input stream

Data is read from the standard input stream cin using the extraction operator >>. We modified our simple example program to prompt for and obtain an integer value from the user via the keyboard:

    #include <iostream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      int value ;

      cout << "Please enter an integer value: " ;
      cin >> value ;
      cout << "The value is " << value << '.' << endl ;
    }

When we compiled and ran this program, we captured the following transcript:

    Please enter an integer value: 456
    The value is 456.

The user entered the characters "456", the extraction operator read and converted the characters to the internal representation of the digit string "456," and assigned the two's complement value of 456 to the integer variable value. Multiple values can be read from the standard input -- the individual values are separated by white space (e.g., spaces.)

The conversion process reads just enough characters to satisfy the extraction operation. This sometimes leads to unexpected programming logic errors. For example, if the user entered "18.0" in response to the prompt, the extraction will read up to the period character, which terminates the integer digit string, "18". The ".0" characters are not read and are left over! The following program illustrates this phenomenon:

    #include <iostream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      int value ;
      char left_overs[256] ;

      cout << "Please enter an integer value: " ;
      cin >> value ;
      cout << "The value is " << value << '.' << endl ;
      cin >> left_overs ;
      cout << "'" << left_overs << "'" << endl ;
    }

We obtained the following transcript when we compiled and ran this program:

    49 > ./a.out
    Please enter an integer value: 18.0
    The value is 18.
    '.0'

Programmer beware!