Input Streams

Input streams are the fundamental, low-level concept in C++ that allows us to read data into our program. Use cases include the following:

• Reading input from a file on the user's hard drive
• Getting data from a hardware device, such as a controller or sensor
• Parsing user input from a command-line interface
• Communicating with other computers over the internet, or another network connection

In this section, we will explore the basics of input streams in C++ and how to work with them effectively.

std::istream and std::cin

The base class for input streams is std::istream. This is an alias for std::basic_istream and is available by including <istream>.

Typically, we include <iostream> instead, which combines basic input streams and output streams.

1#include <iostream>

An example of an input stream is std::cin, which is a stream designed to get input from the terminal/console. This is the same place output from std::cout goes.

We obtain content from an input stream using the >> operator, followed by a location to save that input. This will typically be some form of a string:

1#include <iostream>
2#include <string>
3
4int main() {
5  std::string Input;
6  std::cout << "Please provide input: ";
7  std::cin >> Input; 
8  std::cout << "Input extracted: " << Input;
9}

When running this program, it will pause and ask us for input. Entering an input and pressing return will cause it to be echoed back to us.

1Please provide input: Hello
2Input extracted: Hello

Note that the >> operator extracts one "token" of input. It treats spaces as the token separator. As such, if our input contained spaces (eg, multiple words), only the content before the first space would be extracted.

1Please provide input: Hello World
2Input extracted: Hello

Later in the lesson, we cover different ways to grab input, so we can extract exactly what we want.

std::istringstream

In the previous lesson, we covered string streams and focused on their use as an output stream

String Streams

A detailed guide to C++ String Streams using std::stringstream. Covers basic use cases, stream position seeking, and open modes.

String streams can serve as input streams too. We set this up by creating an object of one of the following types:

• std::istringstream - an input string stream, which we can read content from
• std::stringstream - a bidirectional string stream, which we can both read from and write to

In the following example, we create a std::istringstream and use it to read content into a string:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Stream{"Hello World"};
6  std::string Extract;
7  Stream >> Extract;
8  std::cout << "Input extracted: " << Extract;
9}

1Input extracted: Hello

Input Stream State and Errors

As we work with and run operations on our streams, they maintain an internal collection of flags (a bitmask) representing the state of the stream. The three main flags are as follows:

• eofbit - The end of the input has been reached. "eof" refers to "end-of-file", but applies to any input stream
• failbit - The previous operation failed in a way that did not compromise the stream. For example, an attempt to extract some output failed
• badbit - A previous operation failed in a way that may have left the stream in a state we weren’t expecting. For example, an attempt to insert some input failed

It is a good habit to check our streams for any issues after each read. Four methods might be helpful:

1#include <sstream>
2
3int main() {
4  std::istringstream Stream;
5  if (Stream.good()) {
6    // No bits set
7  }
8
9  if (Stream.fail()) {
10    // failbit or badbit set
11  }
12
13  if (Stream.bad()) {
14    // badbit set
15  }
16
17  if (Stream.eof()) {
18    // eofbit set
19  }
20}

Additionally, we can coerce our stream to a boolean. For example, within an if statement, we can check if our stream is in a good state:

1if (Stream) {
2  // All good
3}

This is equivalent to the expression !Stream.fail() - it will return false if either failbit or badbit is set.

The approach we should use to monitor the state of our stream depends on how our stream is being used.

Below, we try to extract three words from a stream that only has two. Remember, the >> operator returns a reference to our stream, so our stream is getting passed to each if statement, to be coerced to a boolean in the way described above:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Stream{"Hello World"};
6  std::string Extract;
7
8  if (Stream >> Extract) {
9    std::cout << "Input extracted: " << Extract
10              << '\n';
11  }
12
13  if (Stream >> Extract) {
14    std::cout << "Input extracted: " << Extract
15              << '\n';
16  }
17
18  if (!(Stream >> Extract)) {
19    std::cout << "Extraction failed";
20  }
21}

1Input extracted: Hello
2Input extracted: World
3Extraction failed

Below, we compress this into a loop. This is a common pattern for reading from an input:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Stream{"Hello World"};
6  std::string Extract;
7
8  while (Stream >> Extract) {
9    std::cout << "Input extracted: " << Extract
10              << '\n';
11  }
12}

1Input extracted: Hello
2Input extracted: World

Getting Input Position using tellg()

Similar to output streams, our input streams have a position. The position represents where the next input will come from, once we execute a read operation.

We can find out what the position is using the tellg() method:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello World"};
6  std::string Extract;
7
8  std::cout << "Input Position: "
9            << Input.tellg();
10
11  Input >> Extract;
12  std::cout << "\n\nExtracted: " << Extract;
13  std::cout << "\nInput Position: "
14            << Input.tellg();
15
16  Input >> Extract;
17  std::cout << "\n\nExtracted: " << Extract;
18  std::cout << "\nInput Position: "
19            << Input.tellg();
20}

1Input Position: 0
2
3Extracted: Hello
4Input Position: 5
5
6Extracted: World
7Input Position: -1

When tellg() fails, it returns -1. The most common causes for this are:

• We have reached the end of the input stream - there is nothing more to read. That is what happened in the previous example
• The underlying stream we're reading from doesn’t support tellp(). This is extremely uncommon.

Setting Input Position using seekg()

We can change the input position using seekg(). We can set the position to an absolute value by passing a single number:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello World"};
6  std::string Extract;
7
8  Input.seekg(5);
9  Input >> Extract;
10  std::cout << "Extracted: " << Extract;
11
12  Input.seekg(1);
13  Input >> Extract;
14  std::cout << "\nExtracted: " << Extract;
15}

1Extracted: World
2Extracted: ello

We can also offset the position from some anchor, by passing two arguments: a numeric offset, and the anchor to use. We have three options for the anchor:

• std::ios::beg - set the position relative to the beginning of the stream
• std::ios::cur - set the position relative to the current position
• std::ios::end - set the position relative to the end of the stream

Below, we show some examples of this:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"123456789"};
6  std::string Extract;
7
8  // Seek to 2 positions after the stream start
9  Input.seekg(2, std::ios::beg);
10  Input >> Extract;
11  std::cout << "Extracted: " << Extract;
12
13  // Seek 2 positions back from the current
14  Input.seekg(-2, std::ios::cur);
15  Input >> Extract;
16  std::cout << "\nExtracted: " << Extract;
17
18  // Seek to 5 positions before the end
19  Input.seekg(-5, std::ios::end);
20  Input >> Extract;
21  std::cout << "\nExtracted: " << Extract;
22}

1Extracted: 3456789
2Extracted: 89
3Extracted: 56789

Getting Content using std::getline()

The std::getline() function, available within <string>, will extract a line of text from an input stream, and insert it into a std::string

1#include <iostream>
2#include <string>
3
4int main() {
5  std::string Input;
6  std::cout << "Please provide input: ";
7  std::getline(std::cin, Input);
8  std::cout << "Input extracted: " << Input;
9}

1Please provide input: Hello World
2Input extracted: Hello World

The std::getline() function returns a reference to the input stream, which we can use as needed. Below, we replicate our earlier example of extracting input in a loop, until the input stream fails its boolean check:

1#include <iostream>
2#include <sstream>
3#include <string>
4
5int main() {
6  std::istringstream Input{"Hello\nWorld"};
7  std::string Extract;
8  while (std::getline(Input, Extract)) {
9    std::cout << "Extract: " << Extract << '\n';
10  }
11}

1Extract: Hello
2Extract: World

By default, std::getline() reads the steam input line by line, that is, it uses line break characters such as \n as delimiters.

However, we can specify the delimiter we want to use by passing it as the third argument.

Below, we extract "lines" of input, where lines are separated by commas:

1#include <iostream>
2#include <sstream>
3#include <string>
4
5int main() {
6  std::istringstream Input{"Hello,World"};
7  std::string Extract;
8  while (std::getline(Input, Extract, ',')) {
9    std::cout << "Extract: " << Extract << '\n';
10  }
11}

Note - the delimiter is not included in the extract. Additionally, within the stream, the input position is moved past the delimiters, effectively skipping over them.

As such, the delimiters are never included in the text we extract. The previous example has the following output:

1Extract: Hello
2Extract: World

Getting a Character using get()

An alternative to the std::getline() function is the get() function, which is a method on input streams. By default, get() extracts a single character:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello"};
6  char Extract;
7  Input.get(Extract);
8  std::cout << "Extract: " << Extract;
9}

1Extract: H

Similar to other methods, it returns a reference to the stream. Below, we use this to control a loop that extracts everything from the input stream, character by character.

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello"};
6  char Extract;
7  while (Input.get(Extract)) {
8    std::cout << "Extract: " << Extract << '\n';
9  }
10}

1Extract: H
2Extract: e
3Extract: l
4Extract: l
5Extract: o

The get() method also accepts a second argument, which allows us to extract multiple characters. When using this, we typically write the extract to a c-style string - a character array, or char*

Given this is a C-style string, we need to leave an additional space for the null termination character, which denotes where the string ends.

Below, we pass 4 to get(). This causes it to write three characters from our stream to our char*. with the 4th character being reserved for the null terminator.

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello"};
6  char Extract[4];
7  Input.get(Extract, sizeof(Extract));
8  std::cout << "Extract: " << Extract;
9}

1Extract: Hel

Similar to std::getline(), we can pass an additional argument to get(), which will act as a delimiter. The get() method will extract characters until it reaches the limit specified by the second argument, or it encounters the delimiter specified by the third argument.

However, unlike std::getline(), the input position is not moved past the delimiter:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello,World"};
6
7  char Extract[100];
8  Input.get(Extract, sizeof(Extract), ',');
9  std::cout << "Extract: " << Extract;
10
11  // Note: the input position remains before the
12  // comma, so future reads will include it
13  std::string Remainder;
14  Input >> Remainder;
15
16  std::cout << "\nRemainder: " << Remainder;
17}

1Extract: Hello
2Remainder: ,World

Checking the next Character using peek()

The peek() method allows us to look at the next character in the stream, without necessarily extracting it.

Below, we peek at the next character in the stream, but the input position is not moved forward. Therefore, when we come to extract the input later, the character we peeked at is included.

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello"};
6  std::string Extract;
7
8  std::cout << "Next Value: " << Input.peek();
9  Input >> Extract;
10  std::cout << "\nExtracted: " << Extract;
11}

The compiler does not inherently know the type of data that is in our stream - it just sees bytes. When we extract something to a char, for example, the compiler understands it should interpret the byte as a character.

But our use of peek() here does not give the compiler any such hint, So the byte we peeked at is being interpreted as a number:

1Next Value: 72
2Extracted: Hello

In this case, 72 is the ASCII code for an uppercase 'H'.

We can cast it to a character to get the expected output:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello"};
6  std::string Extract;
7
8  std::cout << "Next Value: "
9            << static_cast<char>(Input.peek());
10
11  Input >> Extract;
12  std::cout << "\nExtracted: " << Extract;
13}

1Next Value: H
2Extracted: Hello

Detecting End of File (EOF) using peek()

A common use of peek() is to check for the end of the input. This is called the end of file, even for input streams that are not files.

Earlier, we covered that input streams have an eof() method, that returns true if the end of input was detected. However, the stream may have no further input, but the eof flag has not yet been set.

Often, this is caused by trailing delimiters. For example, calling getline() on a stream containing "Hello\n" will extract "Hello", but will not set the end-of-file flag.

This is because getline() stopped once it reached the new line \n character. It didn’t look past it to notice the end of the file.

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::istringstream Input{"Hello\n"};
6  std::string Extract;
7
8  std::getline(Input, Extract);
9  std::cout << "Extracted: " << Extract;
10
11  if (!Input.eof()) {
12    std::cout << "\nEOF is not true";
13  }
14}

1Extracted: Hello
2EOF is not true

In this scenario, attempting a further read would fail, and set both the eofbit and failbit on our stream. This is not necessarily a problem - our surrounding loop and logic may be able to accommodate that.

However, in some situations, we will need to check whether we reached the end of file before even attempting a read. The peek() method can help us here.

Below, we extract Hello and World from our stream using getline(). There is no further usable input but, because the data has a trailing newline character, our read operations have not yet found the end of the file.

The peek() method will not advance the input position, but it will set the state of our stream based on what it encounters.

In the following example, our peek() operation sees the end of the file, which causes the stream’s state to be updated.

1#include <iostream>
2#include <sstream>
3#include <string>
4
5int main() {
6  // Note the trailing comma
7  std::istringstream Input{"Hello\nWorld\n"};
8  std::string Extract;
9
10  std::getline(Input, Extract);
11  std::cout << "Extracted: " << Extract;
12
13  std::getline(Input, Extract);
14  std::cout << "\nExtracted: " << Extract;
15
16  if (!Input.eof()) {
17    std::cout << "\nWe have not reached EOF...";
18  }
19
20  Input.peek();
21
22  if (Input.eof()) {
23    std::cout << "\n...but now we have";
24  }
25}

1Extracted: Hello
2Extracted: World
3We have not reached EOF...
4...but now we have

Example: Creating and Updating Objects

The main use case for streams is to bridge the gap between data and objects within our program.

For example, the user may have files from our application stored on their system, or data coming in from the internet or another network.

We need to use that data to create C++ objects that we can interact with in the normal way.

Below, we’ll use an istringstream to simulate the data source, but the process is the same across all input streams. In the next lesson, we’ll cover file systems and networking.

Let's create a character based on raw data coming from an input stream. In this example, we’re able to create a full-fledged C++ object using the plain text input "Legolas 80 1" :

1#include <iostream>
2#include <sstream>
3
4using stream = std::istringstream;
5
6class Character {
7 public:
8  Character(stream& Stream) {
9    Stream >> Name;
10    Stream >> Level;
11    Stream >> isAlive;
12  }
13
14  std::string Name;
15  int Level;
16  bool isAlive;
17
18  void Log() {
19    std::cout << Name << " - Level " << Level
20              << (isAlive ? " (Alive)"
21                          : " (Dead)")
22              << '\n';
23  }
24};
25
26int main() {
27  stream Input{"Legolas 80 1"}; 
28  Character Player{Input};
29
30  Player.Log();
31}

1Legolas - Level 80 (Alive)

Given that streams keep track of their input position, we can use the same stream to create a dynamic number of objects:

1#include <iostream>
2#include <sstream>
3#include <vector>
4
5using stream = std::istringstream;
6
Unchanged Code|Show
7class Character {/*...*/}
27
28int main() {
29  stream Input{
30      "Legolas 80 1 Gimli 70 1 Aragorn 60 0"};
31
32  std::vector<Character> Party;
33
34  while (Input.good()) {
35    Party.emplace_back(Input);
36  }
37
38  for (auto& Member : Party) {
39    Member.Log();
40  }
41}

1Legolas - Level 80 (Alive)
2Gimli - Level 70 (Alive)
3Aragorn - Level 60 (Dead)

Working with streams in this way is the key that unlocks many new capabilities. This can include basic functionality like saving a file to the hard drive, and then using that file to restore our program to that state when it’s next opened.

But it’s also the underlying concept that enables us to share the state of objects across multiple machines, running our program at the same time over the internet.

In the next chapter, we’ll build upon these fundamentals, to create architectures that allow us to ramp up the complexity to deal with these more advanced use cases.

We’ll show how to read and write streams from more useful sources, including the hard drive and the internet.

We’ll also introduce different ways to structure the data in the streams, to make it more manageable or performant. We'll first look at JSON, a more versatile and human-readable way of storing and transmitting information:

1[{
2  "name": "Legolas",
3  "level": 10,
4  "isAlive": true,
5}, {
6  "name": "Legolas",
7  "level": 10,
8  "isAlive": true,
9}, {
10  "name": "Legolas",
11  "level": 10,
12  "isAlive": false,
13}]

And we’ll also go in the opposite direction, working with binary streams that are not readable by humans at all, but instead focus on maximizing performance. These are the type of streams we use when creating things like fast-paced multiplayer games.

We’ll also introduce third-party libraries that build on top of streams, abstracting away much of the low-level concerns we’ve covered so far, and allowing us to build our projects more quickly.

Summary

This lesson has taken you through the fundamentals of input streams, from basic input with std::cin to advanced stream manipulation with tellg(), seekg(), and beyond.

We've explored how streams maintain their state, handle errors, and can be used to construct complex objects from incoming data, setting the stage for working with file and network streams in real-world applications.

Main Points Covered

• Basic input operations with std::cin and the limitations of using the >> operator.
• The role of std::istringstream in reading data from string-based sources.
• Understanding and managing stream state flags for error handling.
• Manipulating and querying the stream's position using tellg() and seekg().
• Reading lines and characters from streams with std::getline() and get().
• The use of peek() for previewing stream data without extraction.
• Constructing and initializing objects directly from stream data, demonstrating the practical application of input streams in building dynamic collections of objects.

Next Lesson

Working with the File System

Create, delete, move, and navigate through directories and files using the standard library's filesystem module.

ContinueView Course