String Streams

String streams allow us to create and use a stream that is based on an underlying string. Once we’re familiar with stream-based I/O mechanisms, covered in this chapter, string streams offer us a convenient way to use those techniques to manipulate strings.

String streams are available by including <sstream>:

1#include <sstream>

There are three main types of string streams we are likely to encounter:

• std::istringstream, which is an input stream
• std::ostringstream, which is an output stream
• std::stringstream, which is a bidirectional stream

We’ll use std::ostringstream in this lesson, but the concepts apply to all variants. We cover input streams and bidirectional streams in the next lesson.

Creating String Streams

As with other output streams, we can use the << operator to add content to it:

1#include <sstream>
2
3int main() {
4  std::ostringstream Stream;
5  
6  // Adding content to the stream
7  Stream << "Hello World";
8}

The << operator returns a reference to the stream, so it can be chained:

1#include <sstream>
2
3int main() {
4  std::ostringstream Stream;
5  Stream << "Hello"
6         << " World"; 
7}

Getting the String with str()

The underlying string managed by the string stream is accessible via the str() method:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  Stream << "Hello World";
7
8  std::cout << Stream.str(); 
9}

1Hello World

An immediate use case for string streams is to concatenate strings. Using string streams for this tends to be more performant than any other approach, particularly when the strings are large.

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::string Greeting{"Hello"};
6
7  std::ostringstream Stream;
8  Stream << Greeting << " World"; 
9
10  std::string Result{Stream.str()};
11  std::cout << Result;
12}

1Hello World

Getting Stream Position with tellp()

A key property of streams that makes them usable in the ways we’ve shown is their internal position.

A position is just an integer. For an output stream, it is where the next output will be inserted. Most functions that insert content into our output stream (including the << operator) also update the output position, which affects where future content will be written.

When working with an output stream, we can find out the current output position using the tellp() method:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  std::cout << "Output position: "
7            << Stream.tellp(); 
8
9  Stream << "Hello";
10  std::cout << "\nOutput position: "
11            << Stream.tellp(); 
12
13  Stream << " World";
14  std::cout << "\nOutput position: "
15            << Stream.tellp(); 
16}

1Output position: 0
2Output position: 5
3Output position: 11

In all our examples in both this lesson and the previous one, the output position has been at the end of the stream, ensuring future content gets appended.

But, the output position doesn’t need to be at the end of the stream. For example, string streams have a constructor that lets us set the initial content of our stream.

1std::ostringstream Stream{"Hello"};

However, after construction, the output position is always at 0 even if we provided initial content. This means future writes will occur at the start of the stream, effectively overwriting our initial content.

The following example shows the effect of this:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream{"Hello"};
6
7  std::cout << "Stream contents: "
8    << Stream.str();
9  std::cout << "\nOutput position: "
10    << Stream.tellp();
11
12  Stream << "B";
13  std::cout << "\nStream contents: "
14    << Stream.str();
15  std::cout << "\nOutput position: "
16    << Stream.tellp();
17}

1Stream contents: Hello
2Output position: 0
3Stream contents: Bello
4Output position: 1

Similarly, the str() method of string streams allows us to provide a new string. This resets the content of the stream, but also sets the output position back to 0:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  Stream << "Hello";
7  std::cout << "Stream contents: "
8            << Stream.str();
9
10  std::cout << "\nOutput position: "
11            << Stream.tellp();
12
13  Stream.str("Hello");
14
15  std::cout << "\n\nStream contents: "
16            << Stream.str();
17  std::cout << "\nOutput position: "
18            << Stream.tellp();
19
20  Stream << "B";
21
22  std::cout << "\n\nStream contents: "
23            << Stream.str();
24  std::cout << "\nOutput position: "
25            << Stream.tellp();
26}

1Stream contents: Hello
2Output position: 5
3
4Stream contents: Hello
5Output position: 0
6
7Stream contents: Bello
8Output position: 1

Later in this lesson, we cover an alternative constructor that causes our streams to move their output position to the end after construction and reset.

But, we can also control the positions manually, using seekp(), which we cover next.

Setting Stream Position with seekp()

Output and bidirectional streams have a seekp() method, which allows us to set the output stream position. There are two ways we can use this - we can either set the position absolutely, or relatively.

Let's take a look at setting absolute positions first. We can do this by passing a single number to the function, to define what we want the position to be.

The following example demonstrates this, passing 0 to reset our output position back to the start of the stream:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  Stream << "hello";
7
8  std::cout << "Stream contents: "
9            << Stream.str();
10  std::cout << "\nOutput position: "
11            << Stream.tellp();
12
13  std::cout << "\n\nUsing seekp(0)";
14  Stream.seekp(0); 
15  std::cout << "\nOutput position: "
16            << Stream.tellp();
17
18  std::cout << "\n\nInserting H";
19  Stream << "H";
20  std::cout << "\nStream contents: "
21            << Stream.str();
22  std::cout << "\nOutput position: "
23            << Stream.tellp();
24}

1Stream contents: hello
2Output position: 5
3
4Using seekp(0)
5Output position: 0
6
7Inserting H
8Stream contents: Hello
9Output position: 1

Relative Stream Positions

More commonly, we won’t want to seek an absolute position, rather, we will want to seek relative to some other position. Typical scenarios for this include:

• Seeking forward or backward from our current position
• Seeking to the end of the stream (which we may not know the absolute position of)

We can perform seeks like this by passing a second argument to seekp(). The second argument represents the other position that we want to base our new position on. It has three options:

• std::ios::beg - Set the new position relative to the beginning of the stream (rarely used, as the absolute position is already relative to the beginning)
• std::ios::cur - Set the new position relative to the current position
• std::ios::end - Set the new position relative to the end of the stream

When providing a second argument to seekp(), the first argument then acts as an offset. For example:

• We can advance five steps from our current position by passing 5 and std::ios::cur
• We can seek to the end of the stream by passing 0 and std::ios::end

When using relative seek, our numeric argument can be negative, which moves the position backward.

Below, we use seekp() with an offset of -2 relative to ios::cur to replace the last 2 characters in a stream:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  Stream << "Hello";
7
8  std::cout << "Stream contents: "
9            << Stream.str();
10  std::cout << "\nOutput position: "
11            << Stream.tellp();
12
13  std::cout << "\n\nUsing seekp(-2, ios::cur)";
14  Stream.seekp(-2, std::ios::cur); 
15  std::cout << "\nOutput position: "
16            << Stream.tellp();
17
18  std::cout << "\n\nInserting \"p!\"";
19  Stream << "p!";
20  std::cout << "\nStream contents: "
21            << Stream.str();
22  std::cout << "\nOutput position: "
23            << Stream.tellp();
24}

1Stream contents: Hello
2Output position: 5
3
4Using seekp(-2, ios::cur)
5Output position: 3
6
7Inserting "p!"
8Stream contents: Help!
9Output position: 5

Below, we use the str() method on our string stream, to replace the underlying content. This resets our output position to 0, but we can use seekp() with an offset of 0 relative to ios::end. This moves our position to the end of the stream:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::ostringstream Stream;
6  Stream.str("Hello");
7
8  std::cout << "Stream contents: "
9            << Stream.str();
10  std::cout << "\nOutput position: "
11            << Stream.tellp();
12
13  std::cout << "\n\nUsing seekp(0, ios::end)";
14  Stream.seekp(0, std::ios::end); 
15  std::cout << "\nOutput position: "
16            << Stream.tellp();
17
18  std::cout << "\n\nInserting \" World\"";
19  Stream << " World";
20  std::cout << "\nStream contents: "
21            << Stream.str();
22  std::cout << "\nOutput position: "
23            << Stream.tellp();
24}

1Stream contents: Hello
2Output position: 0
3
4Using seekp(0, ios::end)
5Output position: 5
6
7Inserting " World"
8Stream contents: Hello World
9Output position: 11

Using "at end" mode with ios::ate

Streams provide various options for behavior, typically called open modes.

Most open modes are only relevant to file streams, which we cover later in this chapter. However, the "at end" (std::ios::ate) open mode is also relevant for string streams.

When we enable this, our string stream will automatically seek to the end upon construction, and every time we reset our underlying string by passing an argument to the str() method.

We provide the open modes as the first argument to the string stream constructor, or as the second argument if we’re providing an initial value.

1std::ostringstream A{std::ios::ate};
2std::ostringstream B{"Hello", std::ios::ate};

Several modes can be active simultaneously, as open modes are represented as a bitmask.

The default open mode for std::ostringstream is ios::out, which makes our stream writable. We typically want to maintain that, so we combine ios::out with ios::ate using the | operator:

1std::ostringstream Stream{
2  "Hello", std::ios::out | std::ios::ate};

Note, this is the bitwise | operator, not the boolean || operator. If the | operator is unfamiliar, we have a dedicated lesson covering it, and how it’s used in scenarios like this:

Bitwise Operators and Bit Flags

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

With this flag set, our stream now automatically seeks to the end upon construction, and after every reset using the str() method:

1#include <iostream>
2#include <sstream>
3
4int main() {
5  std::cout << "Initializing with \"Hello\"";
6  std::ostringstream Stream{
7      "Hello", std::ios::out | std::ios::ate}; 
8  std::cout << "\nPosition: " << Stream.tellp();
9
10  std::cout << "\n\nAppending \" World\"";
11  Stream << " World";
12
13  std::cout << "\nStream contents: "
14            << Stream.str();
15
16  std::cout << "\n\nResetting to \"Goodbye\"";
17  Stream.str("Goodbye");
18  std::cout << "\nPosition: " << Stream.tellp();
19
20  std::cout << "\n\nAppending \" Everyone\"";
21  Stream << " Everyone";
22  std::cout << "\nStream contents: "
23            << Stream.str();
24}

1Initializing with "Hello"
2Position: 5
3
4Appending " World"
5Stream contents: Hello World
6
7Resetting to "Goodbye"
8Position: 7
9
10Appending " Everyone"
11Stream contents: Goodbye Everyone

Summary

In this lesson, we delved into C++ string streams, exploring their creation, manipulation, and advanced features like stream positions and open modes.

Main Points

• Introduction to string streams and the types available in C++.
• How to create and use std::ostringstream to append strings.
• Retrieving the underlying string with the str() method.
• Understanding and manipulating the stream's internal position using tellp() and seekp().
• The concept of open modes such as std::ios::ate for managing stream positions automatically.

Next Lesson

Input Streams

A detailed introduction to C++ Input Streams using std::cin and istringstream. Starting from the basics and progressing up to advanced use cases including creating collections of custom objects from our streams.

ContinueView Course