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 allows 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 are an abstraction that allows us to treat a single source as both an input and output stream

All three types of streams 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.

While 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}

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!

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}

1Hello World!
2Done

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}

1Hello World!
2Done

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}

1Hello World!
2Done

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 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.

1#include <iostream>
2
3int main() {
4  std::cout << "Hello World";
5}

1Hello World

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:

1#include <iostream>
2
3int main() {
4  std::string Greeting{"Hello"};
5  std::cout << Greeting << " World";
6}

1Hello World

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

1#include <iostream>
2
3int main() {
4  std::cout << "Hello\nWorld";
5}

1Hello
2World

Stream Manipulators

One way we can modify the behavior of our streams is by inserting manipulators into them. We insert manipulators into streams using the << operator. For example, to make our output stream display numbers in hexadecimal, we would do this:

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

1ff

Most manipulators modify the behavior of the stream for the remainder of its life, or until we insert a manipulator that overrides it. For example, we can revert our stream to treating numbers as decimal by streaming std::dec to it:

1#include <iostream>
2
3int main() {
4  std::cout << std::hex;
5  std::cout << "Hex: " << 255;
6  std::cout << "\nStill Hex: " << 123;
7
8  std::cout << std::dec;
9  std::cout << "\n\nNow Decimal: " << 255;
10  std::cout << "\nStill Decimal: " << 123;
11}

1Hex: ff
2Still Hex: 7b
3
4Now Decimal: 255
5Still Decimal: 123

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}

1377
2255
3ff

These can also be used as standalone functions, where they accept the stream they should apply to as an argument:

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

1377
2255
3ff

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 base 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}

1377
2255
3ff

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}

1true false
21 0

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

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

1true false
21 0

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, std::setprecision;
6  float pi{3.141592};
7  cout << setprecision(1) << pi << '\n';
8  cout << setprecision(2) << pi << '\n';
9  cout << setprecision(3) << pi << '\n';
10  cout << setprecision(-1) << pi;
11}

13
23.1
33.14
43.14159

The precision() function is also available as an output stream method, allowing us to implement the behavior using a different syntax:

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

13.14

std::setw()

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:

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

1Using std::setw(6):
2     1
3    12
4   123
5  1234
6 12345

std::setfill()

We can change the character used for left padding by passing it to std::setfill():

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

1000001
2000012
3000123
4001234
5012345

Ignoring Output Manipulators

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.

The put() Method

The put method streams an individual character to the stream.

1#include <iomanip>
2#include <iostream>
3
4int main() {
5  std::cout.put('A');
6  std::cout.put('\n');
7
8  std::cout << std::setw(5);
9  std::cout << "B\n";
10
11  // This setw will be ignored
12  std::cout << std::setw(10);
13  std::cout.put('C');
14}

1A
2   B
3C

The write() Method

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.write("Hello\n", 6);
6
7  std::cout << std::setw(10);
8  std::cout << "Hello\n";
9
10  // setw will be ignored
11  std::cout << std::setw(10);
12  std::cout.write("Hello\n", 3);
13}

1Hello
2    Hello
3Hel

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 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}

1Hello World

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 occur 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) // ...

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}

1Everything is fine
2Everything is fine

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}

1Something is wrong
2We're all good now

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);

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}

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

Output Streams with Custom Types

Often, we’ll want to make our custom types compatible with output streams. The typical way we do this is 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 returns 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}

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

1#include <iostream>
2
3class Player {
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 Player& P) {
12  Stream << P.Name << " (Level " << P.Level
13         << " " << P.Class << ")";
14  return Stream;
15}

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

1#include <iostream>
2
Player Class|Show
3class Player {/*...*/}
10
<< Overload|Show
11std::ostream& operator<<() {/*...*/}
18
19int main() {
20  Player PlayerOne;
21  std::cout << PlayerOne;
22}

1Roderick (Level 5 Barbarian)

Summary

In this lesson, we've explored C++ output streams, covering everything from basic concepts to advanced techniques for customizing output and handling errors.

Main Points Covered

• Introduction to streams in C++, focusing on output streams for writing data to destinations.
• Distinction between buffered and unbuffered streams, and the significance of flushing buffers.
• The use of the std::cout stream for standard output and how to manipulate data formatting with stream manipulators.
• Explanation of output stream manipulators such as std::oct, std::dec, std::hex, std::boolalpha, std::noboolalpha, std::setprecision(), std::setw(), and std::setfill().
• Overview of the put() and write() methods as alternatives to the << operator for unformatted output.
• Techniques for error handling in output streams, including checking stream states and using std::cerr for error messages.
• Methods for enabling custom types to work with output streams by overloading the << operator.
• Introduction to output stream exceptions for automated error management.

Next Lesson

String Streams

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

ContinueView Course