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.
#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
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.
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
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 usestd::string_viewwithspan().size(). - Output stops at capacity. When the buffer is full the stream fails; characters already written stay valid.
std::format_to_nandstd::to_charsare other ways to format into fixed storage. - Read-only input.
std::ispanstreamaccepts astd::span<const char>too, so you can parse from string literals and read-only data. - Compared with
std::stringstream: usestringstreamwhen 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 thanstd::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 deprecatedstd::strstreamfamily, which did the same job with a worse interface.
Related
std::stringstream, Stream buffers,std::span, Stream states- Lessons: String streams, Spans