header

The Getline Function

The extraction operator ignores whitespace (such as blanks, tabs, and new line characters). During a normal extraction operation, any whitespace characters preceding the item to be extracted are removed from the stream and thrown away (they are ignored). Then the item is extracted from the stream. The extraction operation terminates with the first whitespace character following the item. This terminating whitespace character is not extracted from the stream.

Given this behavior, the extraction operator can only extract string values consisting of a single word. If the string contains two or more words, those words are separated by at least one blank space which would terminate an extraction operation. The getline function remedies that problem. The getline function extracts all of the text left on the current line as a single string (including any blank spaces). That is, it extracts all of the characters in the stream up to the first newline (or end of line) character it encounters. Then the newline character itself is extracted and thrown away.

The getline function has two parameters: the name of the stream from which text is to be extracted and the name of the string that is to be used to store the text:

getline(streamIdentifier, stringIdentifier);

When this statement is executed, every character in the specified stream up to the end of the current line will be extracted and stored as the value of the specified string variable. The end of line character (the newline character) will also be extracted and thrown away.

Using Getline to Read a New Line after Using the Extraction Operator

Using the getline function after a normal extraction operation can cause problems if you are not careful. Suppose we are processing an input stream in which each record consists of two lines of text: a quantity on the first line and the name of an item on the second line where the name may consist of two or more words. The first two records might look like this:

25
Red Pencil
15
Pink Eraser

We extract each quantity using the extraction operator and each item using the getline function:

instream >> qty;
instream.ignore();
getline(instream, item);

In this image, the box on the left represents our executing program and the input stream is shown on the right. The yellow squares represent blank spaces and EOL represents the end of a line. Only the first two records are shown in the stream.

instream >> qty;

The text representation of the quantity is extracted from the stream, converted to an integer value, and assigned to qty. The end of line character for that first line is still in the stream.

instream.ignore();

Ignore the next character in the stream. In effect, the end of line character is extracted and thrown away.

getline(instream, item);

Extract everything up to and including the first end of line character. The string "Red Pencil" is extracted and assigned to item. The end of line character is extracted and thrown away.

Common Mistake 1: Not Using Getline

Now that we've seen the correct way to read this data, we'll look at two common mistakes. The first common mistake is to try to use the extraction operator to read the name of an item:

instream >> qty;
instream >> item;
In this image, the box on the left represents our executing program and the input stream is shown on the right. The yellow squares represent blank spaces and EOL represents the end of a line. Only the first two records are shown in the stream.
instream >> qty;

The text representation of the quantity is extracted from the stream, converted to an integer value, and assigned to qty. The end of line character for that first line is still in the stream.

instream >> item;

The end of line character is extracted and thrown away. Text is extracted up to but not including the first whitespace character. The value "Red" is assigned to item.

Since the extraction operation is whitespace delimited, it read only the first word in the name of the item. Notice that if we now attempt to extract the next quantity from the input stream, we will get a stream failure since "Pencil" does not represent an integer value.

Common Mistake 2: Not Using the Ignore Method

The second common mistake is to forget to use the ignore method after extracting the quantity from the stream and before using the getline function:

instream >> qty;
getline(instream, item);
In this image, the box on the left represents our executing program and the input stream is shown on the right. The yellow squares represent blank spaces and EOL represents the end of a line. Only the first two records are shown in the stream.
instream >> qty;

The text representation of the quantity is extracted from the stream, converted to an integer value, and assigned to qty. The end of line character for that first line is still in the stream.

getline(instream, item);

Everything up to the first end of line character is extracted and assigned to item. In this case that is the empty string since there were no characters preceding the first end of line character. Then the end of line character itself is extracted and thrown away.

Notice that not only is the value of item incorrect, but a subsequent attempt to extract the next quantity will result in a stream failure since "Red" does not represent an integer value.