Output Basics

Output streams are defined in the <ostream> header file. Most programmers include <iostream> in their programs, which in turn includes the headers for both input streams and output streams. The <iostream> header also declares all predefined stream instances: cout, cin, cerr, clog, and the wide versions.

The << operator is the simplest way to use output streams. C++ basic types, such as ints, pointers, doubles, and characters, can be output using <<. In addition, the C++ string class is compatible with <<, and C-style strings are properly output as well. Following are some examples of using <<:

int i = 7;
cout << i << endl;

char ch = 'a';
cout << ch << endl;

string myString = "Hello World.";
cout << myString << endl;

The output is as follows:

7
a
Hello World.

The cout stream is the built-in stream for writing to the console, or standard output. You can “chain” uses of << together to output multiple pieces of data. This is because the << operator returns a reference to the stream as its result so you can immediately use << again on the same stream. Here is an example:

int j = 11;
cout << "The value of j is " << j << "!" << endl;

The output is as follows:

The value of j is 11!

C++ streams correctly parse C-style escape sequences, such as strings that contain . You can also use std::endl to start a new line. The difference between using and endl is that just starts a new line while endl also flushes the buffer. Watch out with endl because too many flushes might hurt performance. The following example uses endl to output and flush several lines of text with just one line of code:

cout << "Line 1" << endl << "Line 2" << endl << "Line 3" << endl;

The output is as follows:

Line 1
Line 2
Line 3

Methods of Output Streams

The << operator is, without a doubt, the most useful part of output streams. However, there is additional functionality to be explored. If you look at the <ostream> header file, you’ll see many lines of overloaded definitions of the << operator to support outputting all kinds of different data types. You’ll also find some useful public methods.

const char* test = "hello there
";
cout.write(test, strlen(test));

cout.put('a');

cout << "abc";
cout.flush();    // abc is written to the console.
cout << "def";
cout << endl;    // def is written to the console.

Handling Output Errors

Output errors can arise in a variety of situations. Perhaps you are trying to open a non-existing file. Maybe a disk error has prevented a write operation from succeeding, for example, because the disk is full. None of the streams’ code you have read up until this point has considered these possibilities, mainly for brevity. However, it is vital that you address any error conditions that occur.

When a stream is in its normal usable state, it is said to be “good.” The good() method can be called directly on a stream to determine whether or not the stream is currently good.

if (cout.good()) {
    cout << "All good" << endl;
}

The good() method provides an easy way to obtain basic information about the validity of the stream, but it does not tell you why the stream is unusable. There is a method called bad() that provides a bit more information. If bad() returns true, it means that a fatal error has occurred (as opposed to any nonfatal condition like end-of-file, eof()). Another method, fail(), returns true if the most recent operation has failed; however, it doesn’t say anything about the next operation, which can either succeed or fail as well. For example, after calling flush() on an output stream, you could call fail() to make sure the flush was successful.

cout.flush();
if (cout.fail()) {
    cerr << "Unable to flush to standard out" << endl;
}

Streams have a conversion operator to convert to type bool. This conversion operator returns the same as calling !fail(). So, the previous code snippet can be rewritten as follows:

cout.flush();
if (!cout) {
    cerr << "Unable to flush to standard out" << endl;
}

Important to know is that both good() and fail() return false if the end-of-file is reached. The relation is as follows: good() == (!fail() && !eof()).

You can also tell the streams to throw exceptions when a failure occurs. You then write a catch handler to catch ios_base::failure exceptions, on which you can use the what() method to get a description of the error, and the code() method to get the error code. However, whether or not you get useful information depends on the Standard Library implementation that you use.

cout.exceptions(ios::failbit | ios::badbit | ios::eofbit);
try {
    cout << "Hello World." << endl;
} catch (const ios_base::failure& ex) {
    cerr << "Caught exception: " << ex.what()
         << ", error code = " << ex.code() << endl;
}

To reset the error state of a stream, use the clear() method:

cout.clear();

Error checking is performed less frequently for console output streams than for file output or input streams. The methods discussed here apply for other types of streams as well and are revisited later as each type is discussed.

Output Manipulators

One of the unusual features of streams is that you can throw more than just data down the chute. C++ streams also recognize manipulators, objects that make a change to the behavior of the stream instead of, or in addition to, providing data for the stream to work with.

You have already seen one manipulator: endl. The endl manipulator encapsulates data and behavior. It tells the stream to output an end-of-line sequence and to flush its buffer. Following are some other useful manipulators, many of which are defined in the <ios> and <iomanip> standard header files. The example after this list shows how to use them.

• boolalpha and noboolalpha: Tells the stream to output bool values as true and false (boolalpha) or 1 and 0 (noboolalpha). The default is noboolalpha.
• hex, oct, and dec: Outputs numbers in hexadecimal, octal, and base 10, respectively.
• setprecision: Sets the number of decimal places that are output for fractional numbers. This is a parameterized manipulator (meaning that it takes an argument).
• setw: Sets the field width for outputting numerical data. This is a parameterized manipulator.
• setfill: Specifies the character that is used to pad numbers that are smaller than the specified width. This is a parameterized manipulator.
• showpoint and noshowpoint: Forces the stream to always or never show the decimal point for floating point numbers with no fractional part.
• put_money: A parameterized manipulator that writes a formatted monetary value to a stream.
• put_time: A parameterized manipulator that writes a formatted time to a stream.
• quoted: A parameterized manipulator that encloses a given string with quotes and escapes embedded quotes.

All of these manipulators stay in effect for subsequent output to the stream until they are reset, except setw, which is only active for the next single output. The following example uses several of these manipulators to customize its output:

// Boolean values
bool myBool = true;
cout << "This is the default: " << myBool << endl;
cout << "This should be true: " << boolalpha << myBool << endl;
cout << "This should be 1: " << noboolalpha << myBool << endl;

// Simulate "%6d" with streams
int i = 123;
printf("This should be '   123': %6d
", i);
cout << "This should be '   123': " << setw(6) << i << endl;

// Simulate "%06d" with streams
printf("This should be '000123': %06d
", i);
cout << "This should be '000123': " << setfill('0') << setw(6) << i << endl;

// Fill with *
cout << "This should be '***123': " << setfill('*') << setw(6) << i << endl;
// Reset fill character
cout << setfill(' ');

// Floating point values
double dbl = 1.452;
double dbl2 = 5;
cout << "This should be ' 5': " << setw(2) << noshowpoint << dbl2 << endl;
cout << "This should be @@1.452: " << setw(7) << setfill('@') << dbl << endl;
// Reset fill character
cout << setfill(' ');

// Instructs cout to start formatting numbers according to your location.
// Chapter 19 explains the details of the imbue call and the locale object.
cout.imbue(locale(""));

// Format numbers according to your location
cout << "This is 1234567 formatted according to your location: " << 1234567 
     << endl;

// Monetary value. What exactly a monetary value means depends on your
// location. For example, in the USA, a monetary value of 120000 means 120000
// dollar cents, which is 1200.00 dollars.
cout << "This should be a monetary value of 120000, "
     << "formatted according to your location: "
     << put_money("120000") << endl;

// Date and time
time_t t_t = time(nullptr);  // Get current system time
tm* t = localtime(&t_t);     // Convert to local time
cout << "This should be the current date and time "
     << "formatted according to your location: "
     << put_time(t, "%c") << endl;

// Quoted string
cout << "This should be: "Quoted string with \"embedded quotes\".": "
     << quoted("Quoted string with "embedded quotes".") << endl;

If you don’t care for the concept of manipulators, you can usually get by without them. Streams provide much of the same functionality through equivalent methods like precision(). For example, take the following line:

cout << "This should be '1.2346': " << setprecision(5) << 1.23456789 << endl;

This can be converted to use a method call as follows. The advantage of the method calls is that they return the previous value, allowing you to restore it, if needed.

cout.precision(5);
cout << "This should be '1.2346': " << 1.23456789 << endl;

For a detailed description of all stream methods and manipulators, consult a Standard Library Reference, for example, the book C++ Standard Library Quick Reference, or online references http://www.cppreference.com/ or http://www.cplusplus.com/reference/.

Input Basics

There are two easy ways to read data by using an input stream. The first is an analog of the << operator that outputs data to an output stream. The corresponding operator for reading data is >>. When you use >> to read data from an input stream, the variable you provide is the storage for the received value. For example, the following program reads one word from the user and puts it into a string. Then the string is output back to the console.

string userInput;
cin >> userInput;
cout << "User input was " << userInput << endl;

By default, the >> operator tokenizes values according to white space. For example, if a user runs the previous program and enters hello there as input, only the characters up to the first white space character (the space character in this instance) are captured into the userInput variable. The output would be as follows:

User input was hello

One solution to include white space in the input is to use get(), which is discussed later in this chapter.

The >> operator works with different variable types, just like the << operator. For example, to read an integer, the code differs only in the type of the variable:

int userInput;
cin >> userInput;
cout << "User input was " << userInput << endl;

You can use input streams to read in multiple values, mixing and matching types as necessary. For example, the following function, an excerpt from a restaurant reservation system, asks the user for a last name and the number of people in their party:

void getReservationData()
{
    string guestName;
    int partySize;
    cout << "Name and number of guests: ";
    cin >> guestName >> partySize;
    cout << "Thank you, " << guestName << "." << endl;
    if (partySize > 10) {
        cout << "An extra gratuity will apply." << endl;
    }
}

Remember that the >> operator tokenizes values according to white space, so the getReservationData() function does not allow you to enter a name with white space. A solution using unget() is discussed later in this chapter. Note also that even though the use of cout does not explicitly flush the buffer using endl or flush(), the text will still be written to the console because the use of cin immediately flushes the cout buffer; they are linked together in this way.

Handling Input Errors

Input streams have a number of methods to detect unusual circumstances. Most of the error conditions related to input streams occur when there is no data available to read. For example, the end of stream (referred to as end-of-file, even for non-file streams) may have been reached. The most common way of querying the state of an input stream is to access it within a conditional. For example, the following loop keeps looping as long as cin remains in a good state:

while (cin) { ... }

You can input data at the same time:

while (cin >> ch) { ... }

The good(), bad(), and fail() methods can be called on input streams, just as on output streams. There is also an eof() method that returns true if the stream has reached its end. Similar as for output streams, both good() and fail() return false if the end-of-file is reached. The relation is again as follows: good() == (!fail() && !eof()).

You should get into the habit of checking the stream state after reading data so that you can recover from bad input.

The following program shows the common pattern for reading data from a stream and handling errors. The program reads numbers from standard input and displays their sum once end-of-file is reached. Note that in command-line environments, the end-of-file is indicated by the user typing a particular character. In Unix and Linux, it is Control+D; in Windows it is Control+Z. The exact character is operating-system dependent, so you will need to know what your operating system requires:

cout << "Enter numbers on separate lines to add. "
     << "Use Control+D to finish (Control+Z in Windows)." << endl;
int sum = 0; 

if (!cin.good()) { 
    cerr << "Standard input is in a bad state!" << endl; 
    return 1; 
} 

int number;
while (!cin.bad()) { 
    cin >> number;
    if (cin.good()) {
        sum += number; 
    } else if (cin.eof()) {
        break; // Reached end of file
    } else if (cin.fail()) {
        // Failure!
        cin.clear(); // Clear the failure state.
        string badToken;
        cin >> badToken; // Consume the bad input.
        cerr << "WARNING: Bad input encountered: " << badToken << endl;
    }
} 
cout << "The sum is " << sum << endl;

Here is some example output of this program:

Enter numbers on separate lines to add. Use Control+D to finish (Control+Z in Windows).
1
2
test
WARNING: Bad input encountered: test
3
^Z
The sum is 6

Input Methods

Just like output streams, input streams have several methods that allow a lower level of access than the functionality provided by the more common >> operator.

string readName(istream& stream)
{
    string name;
    while (stream) { // Or: while (!stream.fail()) {
        int next = stream.get();
        if (!stream || next == std::char_traits<char>::eof())
            break;
        name += static_cast<char>(next);// Append character.
    }
    return name;
}

string readName(istream& stream)
{
    string name;
    char next;    
    while (stream.get(next)) {
        name += next;
    }
    return name;
}

void getReservationData()
{
    string guestName;
    int partySize = 0;
    // Read characters until we find a digit
    char ch;
    cin >> noskipws;
    while (cin >> ch) {
        if (isdigit(ch)) {
            cin.unget();
            if (cin.fail())
                cout << "unget() failed" << endl;
            break;
        }
        guestName += ch;
    }
    // Read partysize, if the stream is not in error state
    if (cin)
        cin >> partySize;
    if (!cin) {
        cerr << "Error getting party size." << endl;
        return;
    }

    cout << "Thank you '" << guestName
        << "', party of " << partySize << endl;
    if (partySize > 10) {
        cout << "An extra gratuity will apply." << endl;
    }
}

char ch1;
cin >> ch1;
cin.putback('e');
// 'e' will be the next character read off the stream.

void getReservationData()
{
    string guestName;
    int partySize = 0;
    // Read characters until we find a digit
    char ch;
    cin >> noskipws;
    while (true) {
        // 'peek' at next character
        ch = static_cast<char>(cin.peek());
        if (!cin)
            break;
        if (isdigit(ch)) {
            // next character will be a digit, so stop the loop
            break;
        }
        // next character will be a non-digit, so read it
        cin >> ch;
        if (!cin)
            break;
        guestName += ch;
    }
    // Read partysize, if the stream is not in error state
    if (cin)
        cin >> partySize;
    if (!cin) {
        cerr << "Error getting party size." << endl;
        return;
    }

    cout << "Thank you '" << guestName
        << "', party of " << partySize << endl;
    if (partySize > 10) {
        cout << "An extra gratuity will apply." << endl;
    }
}

char buffer[kBufferSize] = { 0 };
cin.getline(buffer, kBufferSize);

string myString;
std::getline(cin, myString);

Input Manipulators

The built-in input manipulators, described in the list that follows, can be sent to an input stream to customize the way that data is read.

• boolalpha and noboolalpha: If boolalpha is used, the string false will be interpreted as the Boolean value false; anything else will be treated as the Boolean value true. If noboolalpha is set, zero will be interpreted as false, anything else as true. The default is noboolalpha.
• hex, oct, and dec: Reads numbers in hexadecimal, octal, and base 10, respectively.
• skipws and noskipws: Tells the stream to either skip white space when tokenizing, or to read in white space as its own token. The default is skipws.
• ws: A handy manipulator that simply skips over the current series of white space at the current position in the stream.
• get_money: A parameterized manipulator that reads a monetary value from a stream.
• get_time: A parameterized manipulator that reads a formatted time from a stream.
• quoted: A parameterized manipulator that reads a string enclosed with quotes and in which embedded quotes are escaped.

Input is locale aware. For example, the following code enables your system locale for cin. Locales are discussed in Chapter 19:

cin.imbue(locale(""));
int i;
cin >> i;

If your system locale is U.S. English, you can enter 1,000 and it will be parsed as 1000. If you would enter 1.000, it will be parsed as 1. On the other hand, if your system locale is Dutch Belgium, you can enter 1.000 to get the value of 1000, but entering 1,000 will result in 1. In both cases, you can also just enter 1000 without any digit separators to get the value 1000.