C++ Output Streams

C++ provides several ways to perform input and output operations, including the use of streams. Streams are objects that can receive or provide data. We’re already familiar with the std::cout stream, which lets us send data to the terminal.

But, the use of streams goes far beyond this. They are the underlying system we use to communicate with files, network sockets, hardware devices, and more.

In C++, there are three types of streams:

• Output streams are used to write data to a destination
• Input streams are used to read data from a source
• Bidirectional streams is an abstraction that allows us to treat a single source as both an input and output stream

All three types of stream provide a flexible interface that enables us to work with data in a variety of formats, including binary, text, and even custom formats.

Streams can be used in different ways, depending on the needs of the program. For example, we can use the stream insertion operator << to write data to an output stream, or the stream extraction operator >> to read data from an input stream.

We can also use stream manipulators to control the formatting of the data being read or written. Additionally, streams provide error-handling mechanisms to help ensure that data is processed correctly and that the program can handle unexpected input or output conditions.

In the following sections, we start our exploration of streams by looking at output streams.

Buffered vs Unbuffered Streams

Our C++ streams can be either buffered or unbuffered. An unbuffered stream transfers data one byte at a time. This means that each byte is sent or received as soon as it is ready.

In contrast, a buffered stream uses an intermediate buffer to collect a larger block of data. When the buffer is full, the data is sent to the destination. When the buffer is not full, we can still instruct it to send what it has. This is referred to as flushing the buffer.

Whilst unbuffered streams are more responsive, many systems, such as file systems, are not designed to receive a constant stream of individual bytes. They perform much better with fewer, larger transfers, so streams that interact with these systems benefit from being buffered.

Most output streams are buffered, and depending on the system, this can include std::cout. In an environment where our std::cout output is being buffered, we may not have noticed it.

This is because a buffer is automatically flushed when the object is destructed, which happens automatically when it goes out of scope, or when our program ends.

By delaying the destruction, we may be able to see the buffering:

1#include <iostream>
2#include <thread>
3
4int main() {
5  using namespace std::chrono_literals;
6  std::cout << "Hello world!";
7  std::this_thread::sleep_for(5s);
8  std::cout << "\nDone!";
9}
10

Even though we stream “Hello world!” before we put our thread to sleep, on some terminals, we will not see it until after the 5 seconds have passed. This is because it is being inserted into an intermediate buffer.

Once std::cout is destroyed at the end of main, its destructor will flush the buffer, causing us to see all of our output at once.

1Hello world!
2Done!
3

Flushing Buffers

When working with streams, we can flush their buffer at any time. There are a few ways of doing this. We can call the flush method on the stream:

1#include <iostream>
2#include <thread>
3
4int main() {
5  using namespace std::chrono_literals;
6  std::cout << "Hello world!";
7  std::cout.flush();
8  std::this_thread::sleep_for(5s);
9  std::cout << "\nDone!";
10}
11

We can insert a std::flush into the stream:

1#include <iostream>
2#include <thread>
3
4int main() {
5  using namespace std::chrono_literals;
6  std::cout << "Hello world!" << std::flush;
7  std::this_thread::sleep_for(5s);
8  std::cout << "\nDone!";
9}
10

In addition to inserting a line break, the std::endl symbol also flushes the buffer:

1#include <iostream>
2#include <thread>
3
4int main() {
5  using namespace std::chrono_literals;
6  std::cout << "Hello world!" << std::endl;
7  std::this_thread::sleep_for(5s);
8  std::cout << "Done!";
9}
10

std::ostream and std::cout

Output streams have a type of std::ostream.

Throughout this lesson, we’ll use the familiar std::cout, but it is only only one example of an output stream. There are many more, and we can create our own. The methods and concepts we talk about here apply to all output streams.

Standard library output streams are defined within the <ostream> header. Typically, we include <iostream>, which contains both input and output streams.

std::cout is an output stream that writes to the standard output. This is sometimes also referred to as stdout, the terminal, or the console.

We send items to output streams using the << operator, with the stream on the left, and the object to send on the right. Many built-in objects, such as numeric types, strings, and pointers are compatible with the << operator.

1std::cout << "Hello World";
2

1Hello World
2

We can also support the << operator from within our custom types, which we’ll cover later.

The << operator returns a reference to the stream, so we can chain << operations:

1std::string Greeting {"Hello"};
2std::cout << Greeting << " World";
3

1Hello World
2

Output streams correctly handle escape characters, such as \n to insert a line break

1std::cout << "Hello\nWorld";
2

1Hello
2World
3

Output Manipulators

One way we can modify the behavior of our streams is by inserting manipulators into them. Most manipulators modify the behavior of the stream for the remainder of its life.

The standard library comes with a range of manipulators. The most common ones are listed below

std::oct, std::dec, and std::hex

These manipulators change the numeric base of our stream to octal (base 8), decimal (base 10), or hexadecimal (base 16) respectively. Decimal is the default.

1#include <iostream>
2
3int main() {
4  std::cout << std::oct << 255 << '\n';
5  std::cout << std::dec << 255 << '\n';
6  std::cout << std::hex << 255 << '\n';
7}
8

1377
2255
3ff
4

These can also be used as standalone functions, where they accept a parameter for the stream they should apply to:

1std::oct(std::cout);
2std::dec(std::cout);
3std::hex(std::cout);
4

std::setbase()

From <iomanip> we can use the std::setbase manipulator, passing an integer.

Currently, only 8, 10, or 16 are used, so this is an alternative to std::oct, std::dec, and std::hex. from the previous section. The default value is 10.

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  std::cout << std::setbase(8) << 255 << '\n';
6  std::cout << std::setbase(10) << 255 << '\n';
7  std::cout << std::setbase(16) << 255 << '\n';
8}
9

1377
2255
3ff
4

std::boolalpha and std::noboolalpha

We may have noticed when we stream a boolean to the terminal, true appears as 1, and false appears as 0.

We can modify this behavior by streaming std::boolalpha or std::noboolalpha. The default is std::noboolalpha.

1#include <iostream>
2
3int main() {
4  std::cout << std::boolalpha << true << ' '
5            << false << '\n';
6  std::cout << std::noboolalpha << true << ' '
7            << false << '\n';
8}
9

1true false
21 0
3

These can also be used as standalone functions, where they accept a parameter for the stream they should apply to:

1std::boolalpha(std::cout);
2std::noboolalpha(std::cout);
3

std::setprecision()

This is available within <iomanip> and is used to set the precision with which floating point numbers are displayed.

The default is usually 6, but we can reset to the default dynamically by passing -1 as the precision argument.

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  using std::cout;
6  float pi{3.141592};
7  cout << std::setprecision(1) << pi << '\n';
8  cout << std::setprecision(2) << pi << '\n';
9  cout << std::setprecision(3) << pi << '\n';
10  cout << std::setprecision(-1) << pi;
11}
12

13
23.1
33.14
43.14159
5

precision is also available as an output stream method, allowing us to specify it in a different way:

1#include <iostream>
2
3int main() {
4  std::cout.precision(3);
5  std::cout << 3.1415;
6}
7

13.14
2

std::setw() and std::setfill()

The std::setw() manipulator sets the minimum width of content that is inserted into the stream. Unlike previous manipulators, std::setw will only apply to the next input.

If the input is shorter than the minimum width, it will be “filled” by adding additional characters to the beginning until it reaches the minimum length. This is commonly called left padding.

By default, the padding will be done using space characters, but we can change the character used for padding by passing it to std::setfill():

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  using std::cout;
6
7  cout << std::setfill('0');
8  cout << std::setw(6) << 1 << '\n';
9  cout << std::setw(6) << 12 << '\n';
10  cout << std::setw(6) << 123 << '\n';
11  cout << std::setw(6) << 1234 << '\n';
12  cout << std::setw(6) << 12345 << '\n';
13}
14

1000001
2000012
3000123
4001234
5012345
6

Output Stream put and write methods

Output streams have two alternatives to the << operator: the put and write methods.

The main difference between these methods and the << operator is that they ignore formatting. That is, they ignore any output manipulators like setw that are active in the stream.

put()

The put method streams an individual character to the stream.

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  std::cout << std::setw(5);
6  std::cout << 'A' << std::endl;
7
8  std::cout << std::setw(10);
9  std::cout.put('A');
10}
11

1    A
2A
3

write()

The write method inserts a c-style string (char*) into the stream. It accepts a second argument, representing how many characters to stream.

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  std::cout << std::setw(10);
6  std::cout << "Hello" << std::endl;
7
8  std::cout << std::setw(10);
9  std::cout.write("Hello", 3);
10}
11

1     Hello
2Hel
3

The second argument should be less than or equal to the length of the string. If we want to stream the entire string, we may not know its length if it is a variable.

In that case, we can use use the strlen function on a C-style string, or a method like size() if our string originates from a std::string:

1#include <iostream>
2
3int main() {
4  const char* Hello{"Hello"};
5  std::cout.write(Hello, strlen(Hello));
6
7  std::cout.put(' ');
8
9  std::string World{"World"};
10  std::cout.write(World.c_str(), World.size());
11}
12

1Hello World
2

Output Error Handling and std::cerr

With the basic use of std::cout we’ve been doing so far, it is quite unlikely for anything to go wrong. However, as we work on more advanced projects, stream errors will become more likely, and will be something we need to know how to detect and repair.

Two main types of errors can happen when working with output streams:

• An operation can fail - this is generally considered a recoverable error because the stream itself is still intact
• The stream can become corrupted - this is generally considered unrecoverable

When an operation triggers one of these issues, bit flags within an internal state of the stream object will be set.

The first category of errors will have std::ios::failbit toggled to true, whilst the second category will use std::ios::badbit.

We can check for either of these states by calling methods on our stream:

• good() returns true if neither failbit nor badbit is set
• fail() returns true if either failbit or badbit is set
• bad() returns true if badbit is set

The stream itself also has a boolean conversion operator, so we can, for example, use std::cout as a boolean.

1if (std::cout) // ...
2

If std::cout is truthy, it is equivalent to std::cout.good() being true.

The following code shows various examples where we call these functions to check the state of our stream.

We also use std::cerr if our steam is broken. std::cerr works in much the same way as std::cout but is intended for logging errors. It is a distinct stream, which means it can be used as normal even when std::cout is broken.

1#include <iostream>
2
3int main() {
4  if (std::cout) {
5    std::cout << "Everything is fine\n";
6  }
7
8  if (std::cout.good()) {
9    std::cout << "Everything is fine\n";
10  }
11
12  if (std::cout.fail()) {
13    std::cerr << "Something went wrong\n";
14  }
15
16  if (std::cout.bad()) {
17    std::cerr << "cout is broken\n";
18  }
19}
20

1Everything is fine
2Everything is fine
3

setstate() and clear()

We can manipulate the error state of our streams using setstate() to set a bit flag, and clear() to revert the stream to its original, good state:

1#include <iostream>
2
3int main() {
4  std::cout.setstate(std::ios::failbit);
5
6  if (!std::cout) {
7    std::cerr << "Something is wrong\n";
8  }
9
10  std::cout.clear();
11
12  if (std::cout) {
13    std::cout << "We're all good now";
14  }
15}
16

1Something is wrong
2We're all good now
3

Output Stream Exceptions

Rather than checking our streams for errors, we can instead ask them to throw an exception when an error occurs. We do this using the output stream's exceptions method, passing a bit set for the states for which we want an exception thrown:

1std::cout.exceptions(std::ios::failbit |
2                     std::ios::badbit);
3

Now, when an error occurs, an exception with a type of std::ios::failure will be thrown, which we can catch.

Below, we simulate an error using setstate:

1#include <iostream>
2
3int main() {
4  std::cout.exceptions(std::ios::failbit |
5                       std::ios::badbit);
6
7  try {
8    std::cout.setstate(std::ios::failbit);
9  } catch (const std::ios::failure& e) {
10    std::cerr
11        << "Something went wrong with cout:\n"
12        << e.what();
13  }
14}
15

1Something went wrong with cout:
2ios_base::failbit set: iostream stream error
3

Using Output Streams with Custom Objects

Often, we’ll want to make our custom types compatible with output streams. The typical way we do this by providing an overload for the << operator for ostream objects, where the stream will be the first parameter, and our object will be the second.

To make the << operation chainable, as it is with other types, we need to ensure our function return the ostream reference.

It looks like this:

1std::ostream& operator<<(
2    std::ostream& Stream,
3    const MyType& MyObject) {
4  Stream << "(Information about MyObject)";
5  return Stream;
6}
7

Below, we show a full example of overriding the << operator for a custom Character type.

1#include <iostream>
2
3class Character {
4 public:
5  std::string Name{"Roderick"};
6  std::string Class{"Barbarian"};
7  int Level{5};
8};
9
10std::ostream& operator<<(std::ostream& Stream,
11                         const Character& C) {
12  Stream << C.Name << " (Level " << C.Level
13         << " " << C.Class << ")";
14  return Stream;
15}
16

We can now stream Character objects to an output stream, and get the desired result:

1#include <iostream>
2
3int main() {
4  Character Player;
5  std::cout << Player;
6}
7

1Roderick (Level 5 Barbarian)
2