Formatted Input and Output

Many programs need to move between values and text. A user types a number into a window, and the program needs an integer. A program holds a double and needs to show it in a label. The standard library handles both directions with string streams. A string stream behaves like an ordinary input and output stream, but instead of reading from a keyboard or writing to a file, it reads from and writes to a string held in memory.

This article follows a code-first path. Before reading the explanation of the mechanism, try to predict what each step will produce. The places where your prediction turns out wrong are the most useful clues for understanding how the stream works.

A stringstream can be used for both reading and writing. The same object can accept values through the output operator and hand them back through the input operator. Two more specialized forms exist, each for one direction. An ostringstream is used to build text, and an istringstream is used to parse text that already exists. Both are specializations of the general stringstream, as the diagram below shows.

The two specialized forms have common practical uses. The text collected in an ostringstream can be retrieved with str(), which is typically how values are formatted before the finished string is handed to a graphical user interface. In the other direction, a string received from a graphical user interface can be placed into an istringstream, which lets it be read with formatted input operations.

String streams make it possible to write one general operation that converts any type with a string representation into another type that also has one. The idea is to let the stream do the work. The value is written into the stream as text, then read back out as the target type. If both steps succeed and nothing remains in the stream, the conversion is considered correct.

The source defines this operation as a function template with two type parameters. The first, Target, is the type we want to produce. The second, Source, is the type of the argument. Both default to string. The function creates a local stringstream named interpreter and a result variable of type Target. It then performs three checks in sequence, and it returns the result only if none of them fails. The following sketch follows that description. The leftover check is written out here as one way to express the final check.

The diagram follows the same order as the code. The value enters the stream as text, a read produces the target value, and a final check confirms that the stream holds nothing else. A failure at any of these three points leads to the same outcome, a runtime error reporting that the conversion failed. The source is explicit that the function never returns a partial or guessed result on failure.

A value written into a stringstream can be read back out of it, which makes a complete round trip. The text does not disappear when it is written. It stays in the stream's buffer until a read takes it out and interprets it as a new type.

The source gives two practical guidelines for everyday use. The first is to chain the output and input operators to keep code terse, so that several values can be written or read in a single statement. Chaining works because each operation hands back the stream it was given, so the next operation in the chain acts on that same stream.

The second guideline is to use cout for normal output and cerr for errors. Choosing the stream deliberately makes the purpose of each line of output clear to a reader of the code.