I/O is not built into the C++ language. Instead, it is provided in the standard library. To get the I/O facilities, you will need some of the following include directives in your program:

I/O sources and destinations-- devices, strings, and files—are represented in C++ programs by objects called streams. A stream can be thought of as a sequence of characters. An input stream is a sequence of characters coming from an input device. An output stream is a sequence of characters heading for an output device. When a program needs input, it extracts characters from an input stream. When a program wants to perform output, it inserts characters into an output stream.

Output streams are instances of the class ostream, which is defined in <iostream>. There are several pre-defined output streams:

Initially, all three of these streams are associated with the monitor, but file redirection can reassociate cout with a file or the standard input stream of another program. cerr and clog only differ in their buffering strategies.

The most basic service provided by instances of the ostream class inserts a single character:

We can insert a string using the write function:

Unfortunately, put() and write() only deal with characters. They do not perform translation from binary values to strings. The standard library provides translators that do this. All output translators are represented by the left shift operator. For example:

Because of overloading, this doesn't cause confusion. The C++ compiler can tell by the left operand, cout, that translation, not left shift is to be performed. The right operand tells it what type of translation is to be performed: int to string, double to string, etc.

We can even use translators to write ordinary strings and characters:

Translators return their left operand as a value, thus several output operations can be chained together on a single line:

Because left shift is left-to-right associative, this is the same as:

Which is the same as:

We can even define our own translators. Assume rational numbers (i.e. fractions like 2/3, 1/8, and 7/5) are represented by two ints (numerator and denominator) encapsulated in a struct:

Here are declarations of the rational numbers 3/8 and 2/1:

By defining our own variant of the left shift operator:

our rational numbers will be translated into strings and printed according to our desire:

Note: we must pass os by reference, because it is modified by having the numerator and denominator inserted into it. To allow chaining, we must also return os. Also note that os << rat.num and os << rat.den are calling the integer variant of left shift. They are not recursively calling the variant being defined.

Writing to a file is easy, too. Simply declare an instance of the ofstream class. The constructor expects one input: the name of the file to open or create. The fstream class is derived the ostream class:

So all of the operations discussed above, including left shift, can be used with file streams. For example, this piece of code simply writes some strings and integers to a file called "data1":

Assume Employee is declared as follows:

As we did with rationals, we provide an Employee variant of the left shift operator:

Next, declare a few employees:

As you would expect, this fragment of code writes the three employees to a file caled "data2".

You can use a text editor or word processor to inspec these files.

The translators are handy. Too bad there are no translators for strings. But like files and the monitor, strings can be sinks for a class of streams called output string streams. Like ofstream, the ostringstream class derived from ostream:

Any value that defines a variant of left shift can use the translators to change itself into a string:

Here is a patch of code that uses this template:

Output is easy, but input is filled with pitfalls that await the unwary.

Input streams are instances of the istream class. An ifstream and istringstream class are derived from these:

The standard input, mapped to the keyboard by default, is defined in <iostream>:

The basic service provided by an input stream extracts a single character:

Another version takes a character reference as a parameter:

Of course passing a constant to get fails:

Most streams buffer their characters, so it's possible to put an extracted character back into the input stream:

Or we can simply peek at the next character in the input stream:

This is equivalent to:

Peek is useful when we need to know if the input stream contains a number before we attempt to extract a number:

It's also possible to extract C and C++ strings from an input stream:

The first version extracts up to 79 characters from cin and places them in buffer, followed by a null character. For both functions the extraction stops if the end of file or a newline character is encountered. If a newline character is encountered, it is discarded. This can cause problems in VC++. For example, the getline in the echo function:

discards the newline character before it terminates the input. This means the user must press the Return or Enter key twice to see the echo.

Here's a home-grown version that works:

Translators are available for input streams, too. For example:

extracts characters up to the first white space character (tab, blank, or newline), translates these characters into the binary representation of a double, then assigns this double to x.

As with the insertion operator, several extraction operations can be chained on the same line.

Right shift is right-to-left associative, so this is the same as:

We can read strings and characters using the right shift operator:

An important difference between the extraction operator and getline is that by default, extraction terminates when the first white space is encountered. For example, the following version of echo only echoes the first word of a multi word user input:

Let's build a little square root calculator (you'll need #include <cmath> for this):

The structure of our control loop is standard. It perpetually:

Prompting the user for input is important because extraction is a blocking operations. This means the program blocks until it receives input. Without the prompt this can create the impression that the program has crashed.

On most systems the characters typed are not actually extracted until the user presses the Enter or Return key. In a commercial application it is wise to warn the user about this in the prompt.

Notice that the response is initially read using cin.get(). This fails on most systems because characters are actually extracted from a buffer that contains the entire line that was typed. The buffer still contains the newline character that terminated the numeric input. Because cin.get() doesn't skip white space, it reads this newline character as the response. The response is different from 'q', so the loop is reentered. The replacement:

works because the right shift operator skips white space, including the newline character. However, the user can't type "any" key to continue, as the prompt suggests. Pressing the space bar, tab key, Return key, or Enter key moves the cursor, but doesn't cause any character to be extracted.

To solve this problem, we can flush the input buffer after the number is read. This is done with the synchronize function:

A much bigger problem is what happens if the user enters the string "nine" instead of the number 9? The extraction cin >> x; will fail because the string can't be converted into a number. At that point cin enters the fail state. No input operations can be performed while an input stream is in this state. On most systems this means the program spins wildly around the while loop, prompting the user, but never pausing to read an answer. (Try <Ctrl>c to interrupt.)

When a stream is in the fail state, it turns into 0, the null pointer. The state of the stream can be set back to good using the clear() function. Here's a template function that uses these features to safely read from cin:

The end of the control loop is so common, we might consider making it into a reusable function:

Here's a new version of our control loop, we no longer will need the response variable:

Here's a sample output produced by the program:

We can construct an input file stream from a file name:

If the file isn't found or if its permission level doesn't allow reading, then ifs will enter the fail state and it is set equal to 0:

where error is from my own utils.h:

We can use the null test again to determine when the end of the file is reached. This is more reliable than the eof() function, because that returns false even when only white space characters remain in the file:

For example, the following function computes the average of a file of numbers:

Of course if a non number is encountered in the file, even so much as a punctuation mark, the loop will exit and return the average of the numbers seen.

Everyone's favorite file function changes lower case letters to upper case letters. I'm using the toupper() function defined in the standard C library, so I need to include <cctype>:

Counting words and lines in a file is harder than you'd think. I increment my word counter each time I encounter a non letter following a letter. If the last character in the file was a letter, I increment my word counter again. I increment my line counter each time I encounter a newline character. If the last character in the file was not a newline, I increment my line count once more. Can you think of other improvements?

Grep is a famous UNIX utility that searches a given file line-by-line for a given pattern. It prints lines, with their line numbers, that contain the pattern. The ultimate pattern matching algorithm is the subject of an upper division algorithms course. I simply use string::find():

Notice that all of these functions depend on the fact that get(), getline(), and >> return the stream as a value after each extraction.

Strings can also be character sources for input string streams. Here's the mate to the earlier template function that translated values to strings. This one translates strings into values. We must pass the value as a reference parameter so C++ can infer Value from calls to the function:

Officially, a stream consists of three parts: a translator, a specification, and a buffer. The buffer encapsulates and manages a pointer to the I/O source or sink and an array of characters waiting to be transferred to the program or to the output sink. Buffers are instances of the streambuf class. Istream and ostream instances are translators. Specifications are instances of the ios class. The specification maintains the status and format state of the stream as well as a pointer to the buffer. Oddly, the designers of the stream library picked inheritance as the relationship between translators and specifiers:

A stream inherits functions from its specification that allow programmers to determine its state. For example, if s is a stream, then:

Although the state is an integer, its gets interpreted as a sequence of flags or bits indicating the status of s. We can access these bits directly with the predicates:

If s.good() is false, then subsequent extraction operations are no-ops. If s.bad() is true, forget it. The stream is broken. If s.fail() is true, then the stream can be repaired. Flush the remaining characters and set the state back to the good state using the setstate() function:

These functions are useful when we want to implement our own translators. Recall the Rational number class declared earlier:

When a user enters a rational number, we expect it to have the form a/b or a, where a and b are integers. Failure to meet any of these requirements results in setting the input stream state to fail, and returning immediately. For example, the inputs 3/x, 3\5, and x/5 all result is a failed state. But what happens if the user types a single integer followed by some white space and a newline? We should accept this as a rational with numerator 1. We can use peek() to see if the next character is white space. Of course if the user enters 3 /5, this will be interpreted as 3/1 and the /5 will be left in the buffer:

We can eat whitespace using a function like this one:

Here's a handy function that allows you to determine the number of characters in the input buffer without blocking the program. It directly access the buffer using the rdbuf() function:

Many of the low level functions are used in the following, useful debugging utility. You'll need the include directive and constant declaration:

Output format is controlled by a sequence of flags in the specifier. Users can create their own sequence of format flags by combining predefined masks using bitwise disjunction:

The old flags are saved and the new ones installed by calling the flags function:

In addition, the minimum width of the print field and the fill character can be set:

Now the statement:

produces the output:

The width reverts to 0 after each output operation.

Flags can be set or cleared individually using setf() and unsetf():

Some flags have three values instead of two.

Programmers can control the format and precision of floating point output. For example, the statements:

Produces the output:

Manipulators are functions that can be applied to output streams using the left shift operator syntax.