Reading Input with Streams

Reading a sequence of values from input is one of the most common jobs a program does, and an input stream gives you a convenient way to do it. An iostream carries a state that you can examine to determine whether an operation succeeded. Most of the time you use that state without thinking about it, through a single condition in a loop. This article looks closely at that condition, because it is simple to write and easy to misread.

The question this article answers is: when a read loop finally stops, why did it stop, and what has the container received up to that point? To answer it, you need to know exactly what the while condition tests. Before reading the explanation, try a prediction, because the answer is more interesting than it first looks.

The function below reads integers from an input stream into a vector and returns the vector. Notice that the while statement has a single condition, and that the loop does not count values or look for an end marker.

The key idea is that the condition is a readiness test. It does not ask whether the loop has reached a particular count or a particular marker. It asks only whether the most recent read produced a usable integer. The loop therefore stops at the first item that is not an integer. That item will typically be the end of input, but the mechanism is the same for any non-integer, so a bad token in the middle of the data stops the loop just as surely.

The stream's state holds the information the readiness test reports on. The I/O state of a stream includes formatting information, the error state (for example, whether end of input has been reached), and the kind of buffering in use. For error handling, the error state is the part that matters, because it is what the test checks.

Suppose the input stream contains the text 1 2 x 3. The first two items are integers, the third is not, and a fourth integer follows the bad item. Trace what read_ints does, one pass at a time, and watch both the stream's readiness and the vector's contents.

The same stream can be in different conditions at different points in a program. It starts ready. It can reach the end of input. It can hit an error. And an error that was not serious can be cleared, which makes the stream ready again. The diagram below shows these conditions as states, with the events that move the stream between them.

Notice that end of input is a terminal condition. Reaching it is the usual reason a read loop finishes. An error, by contrast, leads to a decision. The program must decide whether the problem is serious. A serious error stops reading. A non-serious one can be cleared so that reading continues.

Reading a stream is not always a simple choice between success and stopping. A user can set the state to reflect that an error has occurred, and can clear the state if the error was not serious. This gives the program a choice. A failed read can end the whole operation, or it can be recorded, handled, and then followed by further reading.

The before and after view makes one point clear. Clearing the error changes the flag that says the last operation failed. It does not move the input. The rejected token is still waiting at the same position, so the next read attempt starts from there.

After a read fails on a token of the wrong type, the unread input does not vanish. In the input 1 2 x 3, the failed read was aimed at the x. Because the read could not turn x into an integer, the stream is left at that point in the input, and the x is still there to be examined. A program that clears the error and immediately tries to read an integer again will meet the same x unless it does something to move past it.

When a read loop returns something you did not expect, the debugging task is to find the iteration where the stream stopped being ready. Do not start by asking what the loop was supposed to produce. Ask what the input held at each pass. The vector is only a record of the successful reads, so the first failed read is where the result diverged from your expectation.