File Stream Best Practices

Suppose you have written a type that represents a point on a plane, a calendar date, or a bank account. You create an object of that type and try to send it to the output stream the same way you would send a number or a word. Built-in values already know how to appear on a screen or in a file. Your own type does not. The stream has no idea how your type should look as text, so you have to tell it.

The source material states the goal directly: you can define << and >> operators for user-defined types whose values have a meaningful textual representation. The phrase meaningful textual representation is the key condition. If a value can be sensibly written as text, and read back from text, it is a good candidate for input and output operators. This article focuses on the output side with << and then shows how the same approach extends to input with >>.

Think of the stream as a general-purpose channel. It carries text to a destination, such as a screen or a file. When you write an integer or a floating-point number into it, the stream already has the knowledge needed to turn that value into characters. A custom type is different. Its fields might be numbers, but the meaningful picture of the whole object, such as the two coordinates of a point written in parentheses, is something only your type can define.

You can define the << operator for your own type. Once it is defined, the operator is used in the same way as the built-in ones: you write the stream and the value on either side of the operator, and the stream carries the textual form of the value to its destination. Because the stream classes are left alone, your new operator sits alongside the existing ones and extends what the stream can handle.

The operator is responsible for turning the value into text and writing that text to the stream. The stream then delivers the text to its destination. The custom type's knowledge of its own representation is what makes the output meaningful, while the stream remains a general-purpose channel that does not need to know about points.

In a single statement, several values are often sent to the stream one after another. Each << takes the stream produced by the previous step and returns it for the next one. When one of those values is your custom type, the statement dispatches to your operator at exactly that point in the chain, and then control returns to the stream so the chain can continue.

Read the chain from left to right. The object passed to the next operator is always the stream itself, so the text from your Point operator ends up between the text that came before it and the text that comes after it, in the order the statement lists them.

Once a formatting choice has been made on a stream, it can change how the following values appear. Manipulators are the tools for making these choices. The source gives two rules about their reach: precision() specifications apply to all following floating-point output operations, and floating-point format specifications, such as the scientific format, also apply to all following floating-point output operations. In other words, these effects persist; they are not limited to the single value that follows the manipulator.

Standard manipulators come from specific headers. When you use standard manipulators in general, include the ios header. When a manipulator takes an argument, such as a number of digits, include the iomanip header as well. Setting a precision with a value therefore needs iomanip, which is the header to remember whenever a manipulator is given a value.