Chapter 15
Demystifying C++ I/O
WHAT’S IN THIS CHAPTER?
- What streams are
- How to use streams for input and output of data
- What the available standard streams are in the Standard Library
A program’s fundamental job is to accept input and produce output. A program that produces no output of any sort would not be very useful. All languages provide some mechanism for I/O, either as a built-in part of the language or through an OS-specific API. A good I/O system is both flexible and easy to use. Flexible I/O systems support input and output through a variety of devices, such as files and the user console. They also support reading and writing of different types of data. I/O is error-prone because data coming from a user can be incorrect or the underlying file system or other data source can be inaccessible. Thus, a good I/O system is also capable of handling error conditions.
If you are familiar with the C language, you have undoubtedly used printf() and scanf(). As I/O mechanisms, printf() and scanf() are certainly flexible. Through escape codes and variable placeholders, they can be customized to read in specially formatted data, or output any value that the formatting codes permit, which is currently limited to integer/character values, floating point values, and strings. However, printf() and scanf() falter on other measures of good I/O systems. They do not handle errors particularly well, they are not flexible enough to handle custom data types, and, worst of all in an object-oriented language like C++, they are not at all object oriented!
C++ provides a more refined method of input and output through a mechanism known as streams. Streams are a flexible and object-oriented approach to I/O. In this chapter, you will learn how to use streams for data output and input. You will also learn how to use the stream mechanism to read from various sources and write to various destinations, such as the user console, files, and even strings. This chapter covers the most commonly used I/O features.
The stream metaphor takes a bit of getting used to. At first, streams may seem more complex than traditional C-style I/O, such as printf(). In reality, they seem complicated initially only because there is a deeper metaphor behind streams than there is behind printf(). Don’t worry though; after a few examples, you’ll never look back.
What Is a Stream, Anyway?
Chapter 1 compares the cout stream like a laundry chute for data. You throw some variables down the stream, and they are written to the user’s screen, or console. More generally, all streams can be viewed as data chutes. Streams vary in their direction and their associated source or destination. For example, the cout stream that you are already familiar with is an output stream, so its direction is “out.” It writes data to the console so its associated destination is “console.” There is another standard stream called cin that accepts input from the user. Its direction is “in,” and its associated source is “console.” Both cout and cin are predefined instances of streams that are defined within the std namespace in C++. The following table gives a brief description of all predefined streams. The difference between buffered and unbuffered streams is explained in a later section:
STREAM | DESCRIPTION |
cin | An input stream, reads data from the “input console.” |
cout | A buffered output stream, writes data to the “output console.” |
cerr | An unbuffered output stream, writes data to the “error console,” which is often the same as the “output console.” |
clog | A buffered version of cerr. |
Note that graphical user interface applications normally do not have a console; i.e., if you write something to cout, the user will not see it. If you are writing a library, you should never assume the existence of cout, cin, cerr or clog because you never know if your library will be used in a console or in a GUI application.
Every input stream has an associated source. Every output stream has an associated destination.
Another important aspect of streams is that they include data but also have a so-called current position. The current position is the position in the stream where the next read or write operation will take place.
Stream Sources and Destinations
Streams as a concept can be applied to any object that accepts data or emits data. You could write a stream-based network class or stream-based access to a MIDI-based instrument. In C++, there are three common sources and destinations for streams.
You have already read many examples of user, or console, streams. Console input streams make programs interactive by allowing input from the user during run time. Console output streams provide feedback to the user and output results.
File streams, as the name implies, read data from a file system and write data to a file system. File input streams are useful for reading in configuration data and saved files or for batch processing file-based data. File output streams are useful for saving state and providing output. File streams subsume the functionality of the C functions fprintf(), fwrite(), and fputs()for output, and fscanf(), fread(), and fgets() for input.
String streams are an application of the stream metaphor to the string type. With a string stream, you can treat character data just as you would treat any other stream. For the most part, this is merely a handy syntax for functionality that could be handled through methods on the string class. However, using stream syntax provides opportunities for optimization and can be far more convenient than direct use of the string class. String streams subsume the functionality of sprintf(), sprintf_s(), and other forms of C string formatting functions.
The rest of this section deals with console streams (cin and cout). Examples of file and string streams are provided later in this chapter. Other types of streams, such as printer output or network I/O are often platform dependent, so they are not covered in this book.
Output with Streams
Output using streams is introduced in Chapter 1 and is used in almost every chapter in this book. This section will briefly revisit some of the basics and will introduce material that is more advanced.
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 the standard console output stream, cout.
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 = "Marni is adorable."; cout << myString << endl;
Code snippet from OutputBasicsOutputBasics.cpp
The output is as follows:
7 a Marni is adorable.
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. For example:
int j = 11; cout << "On a scale of 1 to cute, Marni ranks " << j << "!" << endl;
Code snippet from OutputBasicsOutputBasics.cpp
The output is as follows:
On a scale of 1 to cute, Marni ranks 11!
C++ streams will correctly parse C-style escape codes, such as strings that contain , but it is much more hip to use the built-in endl mechanism for this purpose. The following example uses endl, which is defined in the std namespace to represent an end-of-line character and to flush the output buffer. Several lines of text are output using one line of code.
cout << "Line 1" << endl << "Line 2" << endl << "Line 3" << endl;
Code snippet from OutputBasicsOutputBasics.cpp
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 take a peek at the <ostream> header file, you’ll see many lines of overloaded definitions of the << operator. You’ll also find some useful public methods.
put() and write()
put() and write() are raw output methods. Instead of taking an object or variable that has some defined behavior for output, put() accepts a single character, while write() accepts a character array. The data passed to these methods is output as is, without any special formatting or processing. For example, the following function takes a C-style string and outputs it to the console without using the << operator:
void rawWrite(const char* data, int dataSize) { cout.write(data, dataSize); }
Code snippet from WriteWrite.cpp
The next function writes the given index of a C-style string to the console by using the put() method:
void rawPutChar(const char* data, int charIndex) { cout.put(data[charIndex]); }
Code snippet from PutPut.cpp
flush()
When you write to an output stream, the stream does not necessarily write the data to its destination right away. Most output streams buffer, or accumulate data instead of writing it out as it comes in. The stream will flush, or write out the accumulated data, when one of the following conditions occurs:
- A sentinel, such as the endl marker, is reached.
- The stream goes out of scope and is destructed.
- Input is requested from a corresponding input stream (i.e., when you make use of cin for input, cout will flush). In the section on file streams, you will learn how to establish this type of link.
- The stream buffer is full.
- You explicitly tell the stream to flush its buffer.
One way to explicitly tell a stream to flush is to call its flush() method, as in the code that follows:
cout << "abc"; cout.flush(); // abc is written to the console. cout << "def"; cout << endl; // def is written to the console.
Code snippet from Flushflush.cpp
Not all output streams are buffered. The cerr stream, for example, does not buffer its output.
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). Another method, fail(), returns true if the most recent operation has failed, implying that the next operation will also fail. For example, after calling flush() on an output stream, you could call fail() to make sure the stream is still usable.
cout.flush(); if (cout.fail()) { cerr << "Unable to flush to standard out" << endl; }
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 is compiler-dependent:
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; }
Code snippet from ExceptionsExceptions.cpp
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 streams 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. Writes a formatted money amount to a stream.
- put_time. Writes a formatted time to a stream.
The following example uses several of these manipulators to customize its output. The example also uses the concept of locales, discussed in Chapter 14.
// 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; // Format numbers according to your location cout.imbue(locale("")); cout << "This is 1234567 formatted according to your location: " << 1234567 << endl; // C++11 put_money: cout << "This should be a money amount of 1200, " << "formatted according to your location: " << put_money("120000") << endl; // C++11 put_time: time_t tt; time(&tt); tm t; localtime_s(&t, &tt); cout << "This should be the current date and time " << "formatted according to your location: " << put_time(&t, "%c") << endl;
Code snippet from ManipulatorManipulator.cpp
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.234567 << endl;
This can be converted to use a method call as follows:
cout.precision(5); cout << "This should be '1.2346': " << 1.23456789 << endl;
Code snippet from ManipulatorManipulator.cpp
See the Standard Library Reference resource on the website for details.
Input with Streams
Input streams provide a simple way to read in structured or unstructured data. In this section, the techniques for input are discussed within the context of cin, the console input stream.
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;
Code snippet from Inputstring.cpp
By default, the >> operator will tokenize 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) will be 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(), 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;
Code snippet from Inputint.cpp
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; } }
Code snippet from InputgetReservationData.cpp
Note that the >> operator will tokenize 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.
If you get confused between << and >>, just think of the angles as pointing toward their destination. In an output stream, << points toward the stream itself because data is being sent to the stream. In an input stream, >> points toward the variables because data is being stored.
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.
get()
The get() method allows raw input of data from a stream. The simplest version of get()returns the next character in the stream, though other versions exist that read multiple characters at once. get() is most commonly used to avoid the automatic tokenization that occurs with the >> operator. For example, the following function reads a name, which can be made up of several words, from an input stream until the end of the stream is reached:
string readName(istream& inStream) { string name; while (inStream.good()) { int next = inStream.get(); if (next == EOF) break; name += next;// Implicitly convert to a char and append. } return name; }
Code snippet from GetGet.cpp
There are several interesting observations to make about this readName() function:
- Its parameter is a non-const reference to an istream, not a const reference. The methods that read in data from a stream will change the actual stream (most notably, its position), so they are not const methods. Thus, you can’t call them on a const reference.
- The return value of get() is stored in an int, not in a char. Because get() can return special non-character values such as EOF (end-of-file), ints are used. When next is appended to a string, it is implicitly converted to a char, and when it is appended to a wstring, it is converted to a wchar_t.
readName() is a bit strange because there are two ways to get out of the loop. Either the stream can get into a “not good” state, or the end of the stream is reached. A more common pattern for reading from a stream uses a different version of get() that takes a reference to a character and returns a reference to the stream. This pattern takes advantage of the fact that evaluating an input stream within a conditional context will result in true only if the stream is available for additional reading. Encountering an error or reaching the end-of-file both cause the stream to evaluate to false. The underlying details of the conversion operations required to implement this feature are explained in Chapter 18. The following version of the same function is a bit more concise:
string readName(istream& inStream) { string name; char next; while (inStream.get(next)) { name += next; } return name; }
Code snippet from GetGet.cpp
unget()
For most purposes, the correct way to think of an input stream is as a one-way chute. Data falls down the chute and into variables. The unget() method breaks this model in a way by allowing you to push data back up the chute.
A call to unget() causes the stream to back up by one position, essentially putting the previous character read back on the stream. You can use the fail() method to see if unget() was successful or not. For example, unget() can fail if the current position is at the beginning of the stream.
The getReservationData() function seen earlier in this chapter did not allow you to enter a name with white space. The following code uses unget() to allow white space in the name. The code reads character by character and checks whether the character is a digit or not. If the character is not a digit, it is added to guestName. If it is a digit, the character is put back into the stream using unget(), the loop is stopped, and the >> operator is used to input an integer, partySize. The meaning of noskipws is discussed later in the section “Input Manipulators.”
void getReservationData() { string guestName; int partySize = 0; // Read letters until we find a non-letter char ch; cin >> noskipws; while (cin >> ch) { if (isdigit(ch)) { cin.unget(); if (cin.fail()) cout << "unget() failed" << endl; break; } guestName += ch; } // Read partysize cin >> partySize; cout << "Thank you '" << guestName << "', party of " << partySize << endl; if (partySize > 10) { cout << "An extra gratuity will apply." << endl; } }
Code snippet from UngetUnget.cpp
putback()
putback(), like unget(), lets you move backward by one character in an input stream. The difference is that the putback() method takes the character being placed back on the stream as a parameter:
char ch1; cin >> ch1; cin.putback(ch1); // ch1 will be the next character read off the stream.
peek()
The peek() method allows you to preview the next value that would be returned if you were to call get(). To take the chute metaphor perhaps a bit too far, you could think of it as looking up the chute without a value actually falling down it.
peek() is ideal for any situation where you need to look ahead before reading a value. For example, the following code implements the getReservationData() function that allows white space in the name, but uses peek() instead of unget():
void getReservationData() { string guestName; int partySize = 0; // Read letters until we find a non-letter char ch; cin >> noskipws; while (true) { // 'peek' at next character ch = cin.peek(); if (!cin.good()) 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; guestName += ch; } // Read partysize cin >> partySize; cout << "Thank you '" << guestName << "', party of " << partySize << endl; if (partySize > 10) { cout << "An extra gratuity will apply." << endl; } }
Code snippet from PeekPeek.cpp
getline()
Obtaining a single line of data from an input stream is so common that a method exists to do it for you. The getline() method fills a character buffer with a line of data up to the specified size. The specified size includes the