Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Strings and I/O

C++ std::spanstream (C++23)

Reference for C++23 std::spanstream, ispanstream and ospanstream: format text into a fixed char buffer or parse from one without allocating memory.

std::ispanstream, std::ospanstream and std::spanstream (header <spanstream>, added in C++23) are string-stream-like classes that work on a buffer you already own. std::stringstream allocates and grows its own std::string; a span stream instead reads from or writes into a std::span<char> that you hand it. It never allocates and never copies the data.

That makes them a good fit for fixed-size character arrays, memory-mapped data, network buffers and code that must not call the allocator. The trade-off is that the buffer has a fixed capacity: writing past the end puts the stream into a failed state instead of growing.

C++
#include <spanstream>

char buffer[64];
std::ospanstream out{std::span<char>(buffer)};
out << "x = " << 42;
std::span<char> written = out.span();   // only the characters written so far

Try it

C++ Formatting into a fixed buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Parsing from a buffer and running out of room

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
template<class CharT, class Traits = std::char_traits<CharT>>
class basic_ispanstream;     // input;  typedef ispanstream  (char)
class basic_ospanstream;     // output; typedef ospanstream  (char)
class basic_spanstream;      // both;   typedef spanstream   (char)

explicit basic_ospanstream(std::span<CharT> s,
                           std::ios_base::openmode mode = std::ios_base::out);
std::span<CharT> span() const noexcept;        // ospanstream, spanstream
std::span<const CharT> span() const noexcept;  // ispanstream
void span(std::span<CharT> s) noexcept;        // attach a new buffer
Name Description
s The existing buffer. It must outlive the stream.
mode Open mode. For output streams std::ios::ate starts writing at the end of the span.

Returns: span() returns the part of the buffer in use: the characters written so far for an output stream, or the whole attached buffer for an input stream.

Errors: none are thrown by default. Writing past the end sets badbit or failbit on the stream; check it with good() or if (out).

Usage notes

  • No allocation, no copy. The text exists exactly once, in your buffer. You are responsible for its lifetime: a span stream over a destroyed array is a dangling reference.
  • Not null-terminated. The stream writes only what you insert. If you need a C string afterwards, write '\0' yourself or use std::string_view with span().size().
  • Output stops at capacity. When the buffer is full the stream fails; characters already written stay valid. std::format_to_n and std::to_chars are other ways to format into fixed storage.
  • Read-only input. std::ispanstream accepts a std::span<const char> too, so you can parse from string literals and read-only data.
  • Compared with std::stringstream: use stringstream when the size is unknown, and a span stream when it is bounded and you care about allocation. Locale and format flags still apply, so formatted output can be slower than std::to_chars.
  • C++23 library feature. It needs a standard library that defines __cpp_lib_spanstream (GCC 12 and later, MSVC 19.31 and later, libc++ 17 and later). It replaces the deprecated std::strstream family, which did the same job with a worse interface.