Defining Custom Input Operations

Reading a single number or a single word from a stream is straightforward. The extraction operator already knows how to turn characters into a value of a built-in type, so a program can read the value and move on. Real input is often richer than that. A line of text might describe a whole record, with several fields arranged in a fixed pattern, such as a name and a number placed inside a particular set of punctuation. When your program needs to fill a structure, such as an entry holding a name and a number, from text like that, the built-in operators are not enough. You need to write your own input operator for the type.

The source material uses an entry type holding a name and a number, and it expects the text to look like a brace, a quoted name, a comma, a number, and a closing brace. This article follows that one format. The format itself is not the important part. The important part is the pattern that any custom input operator follows: check each expected piece, stop cleanly when something is wrong, and report the problem back to the caller.

Before reading the mechanics, run the operator on two inputs and compare what happens. The first input is the well-formed line in which an opening brace is followed by the quoted name ann, a comma, the number 7, and a closing brace. The second input is the malformed line that contains the same characters except that the comma is missing between the name and the number. Both lines contain the same characters apart from that one comma, so any difference in the outcome comes entirely from the format check.

Two things are worth watching in each run. The first is what ends up in the entry. The second is what the stream reports once the call returns. The two runs look identical until the operator reaches the comma, and that is the exact spot where its logic decides the outcome.

Inside the operator, each step is a condition that must succeed before the next step runs. The operator reads a character and checks that it is an opening brace. It then reads the next character and checks that it is a quote. Next it collects characters one at a time until it reaches a closing quote, and those characters become the name. After that it reads a character and checks for a comma, then reads a number and a closing brace. Only when all of these checks succeed does the operator copy the name and number into the entry.

The diagram shows the decision structure. Every decision that answers no sends control to the same failure exit, which is why the operator needs only one place that reports errors. The success path is the only path that touches the entry. Because checks happen in order, a failure at an early check means the later pieces of the input are never examined at all.

When a check fails, the operator does not throw an error and does not print a message. Instead it marks the stream itself. The source uses a state flag named failbit on the stream for this purpose. Setting that flag records that the read did not succeed, and the caller discovers the result by testing the stream after the call returns.

The reason the entry stays untouched is that the assignment happens only on the success path. The operator collects the name first, but it holds that text without writing it into the entry, and it copies both the name and the number only after every check has passed. A failed read therefore never leaves the caller's object holding partial data, such as a name with no number.

An input operation hands back a reference to the stream it read from. Because of that, the whole operation can be used as a condition. Writing a check such as reading into a variable and then asking whether the read worked turns the operation into a question: did the read from the stream into that variable succeed? The answer depends on the state the stream is in after the attempt.

The operator's signature takes the stream and a reference to the entry, and it returns a reference to the stream. Both the input and the output are references, so the operator writes directly into the caller's entry and returns the caller's own stream rather than a copy. Because the stream is returned on both the success path and the failure path, the calling code looks the same either way. The same test works whether the read worked or not, and the failure flag remains visible to any later reads that check the stream first.

In practice this means the caller writes one test around the read. If the test passes, the entry holds a complete record and the program can use it. If the test fails, the program takes its failure branch, and the entry was never modified by the failed attempt.

Each token in the expected text corresponds to one piece the operator must read and check. The opening brace marks the start of a record. The quoted name is collected up to the closing quote and becomes the name field. The comma separates the name from the number. The number is read and copied into the number field. The closing brace marks the end of the record. A check exists for each of these pieces, and the checks run in the same left-to-right order as the text.

Notice that the format check and the field assignment are separate steps. The operator first confirms that each token is in its expected place. Only when the whole pattern matches does it perform the assignment. This separation is what keeps the target object clean when the input is malformed.