std::basic_...ic_stringbuf(3)

🌸 NAME

okay so bestie, this is the page for std::basic_stringbuf::basic_stringbuf — literally the constructor of std::basic_stringbuf. The header calls it std::basic_...ic_stringbuf(3), and it comes from the C++ Standard Libary manual (yes, “Libary” with one r, we are not fixing it 💅). The NAME line is also just std::basic_stringbuf::basic_stringbuf twice with a dash, because apparently they wanted to make absolutely sure you got it.

---

✨ Synopsis ✨

Here’s the overload squad, exactly as the page lays it out, version tags included. No cap, all of these are real:

// (1) (until C++11)
explicit basic_stringbuf( std::ios_base::openmode which =
                              std::ios_base::in |
                              std::ios_base::out );

// (2) (since C++11)
explicit basic_stringbuf( std::ios_base::openmode which );
basic_stringbuf()
    : basic_stringbuf( std::ios_base::in | std::ios_base::out ) {}

// (3)
explicit basic_stringbuf( const std::basic_string<CharT, Traits, Allocator>& s,
                          std::ios_base::openmode which =
                              std::ios_base::in |
                              std::ios_base::out );

// (4) (since C++20)
explicit basic_stringbuf( std::basic_string<CharT, Traits, Allocator>&& s,
                          std::ios_base::openmode which =
                              std::ios_base::in |
                              std::ios_base::out );

// (5) (since C++20)
basic_stringbuf( std::ios_base::openmode which, const Allocator& a );

// (6) (since C++20)
explicit basic_stringbuf( const Allocator& a )
    : basic_stringbuf( std::ios_base::in | std::ios_base::out, a ) {}

// (7) (since C++20)
template< class SAlloc >
explicit basic_stringbuf( const std::basic_string<CharT, Traits, SAlloc>& s,
                          std::ios_base::openmode which =
                              std::ios_base::in |
                              std::ios_base::out );

// (8) (since C++20)
template< class SAlloc >
basic_stringbuf( const std::basic_string<CharT, Traits, SAlloc>& s,
                 std::ios_base::openmode which, const Allocator& a );

// (9) (since C++20)
template< class SAlloc >
basic_stringbuf( const std::basic_string<CharT, Traits, SAlloc>& s,
                 const Allocator& a )
    : basic_stringbuf( s, std::ios_base::in | std::ios_base::out, a ) {}

// (10) (since C++26)
template< class StringViewLike >
explicit basic_stringbuf( const StringViewLike& t,
                          std::ios_base::openmode which =
                              std::ios_base::in |
                              std::ios_base::out );

// (11) (since C++26)
template< class StringViewLike >
basic_stringbuf( const StringViewLike& t,
                 std::ios_base::openmode which, const Allocator& a );

// (12) (since C++26)
template< class StringViewLike >
basic_stringbuf( const StringViewLike& t, const Allocator& a );

// (13) (since C++11)
basic_stringbuf( basic_stringbuf&& rhs );

// (14) (since C++20)
basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a );

// (15) (since C++11)
basic_stringbuf( const basic_stringbuf& rhs ) = delete;

🧚 the init deets

The std::basic_streambuf base and the exposition-only data members buf and mode are initialized like this:

• (1) — std::basic_streambuf base: implementation-defined (see below); buf: default-initialized; mode: which.
• (2) — std::basic_streambuf base: implementation-defined (see below); buf: default-initialized; mode: std::ios_base::in | std::ios_base::out.
• (3) — std::basic_streambuf base: default-initialized; buf: s; mode: which.
• (4) — std::basic_streambuf base: default-initialized; buf: std::move(s); mode: which.
• (5) — std::basic_streambuf base: default-initialized; buf: a; mode: which.
• (6) — std::basic_streambuf base: default-initialized; buf: a; mode: std::ios_base::in | std::ios_base::out.
• (7) — std::basic_streambuf base: default-initialized; buf: s; mode: which.
• (8) — std::basic_streambuf base: default-initialized; buf: {s, a}; mode: which.
• (9) — std::basic_streambuf base: default-initialized; buf: {s, a}; mode: std::ios_base::in | std::ios_base::out.
• (10) — std::basic_streambuf base: default-initialized; buf: {sv, Allocator()}; mode: which.
• (11) — std::basic_streambuf base: default-initialized; buf: {sv, a}; mode: which.
• (12) — std::basic_streambuf base: default-initialized; buf: {sv, a}; mode: std::ios_base::in | std::ios_base::out.
• (13) — std::basic_streambuf base: rhs; buf: std::move(rhs).str(); mode: rhs.mode.
• (14) — std::basic_streambuf base: (copy constructed); buf: {std::move(rhs).str(), a}; mode: rhs.mode.

After initializing these subobjects, overloads (3-12) initialize the input and output sequences as if by calling init_buf_ptrs().

• 1,2) — Overload (1) (until C++11) and (2) (since C++11) is the default constructor. It is implementation-defined whether the sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are initialized to null pointers.
• 5,6) — When the construction is complete, str.empty() is true.
• 7) — This overload participates in overload resolution only if std::is_same_v<SAlloc, Allocator> is false.
• 10-12) — Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then it is used as above in the table. These overloads participate in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true.
• 13,14) — Overload (13) is the move constructor. It is implementation-defined whether the six sequence pointers in *this obtain the values which rhs had. When the construction is complete, rhs is empty but usable, and:
  • Let rhs_p refer to the state of rhs just prior to this construction, the following expressions will evaluate to true:
    • str() == rhs_p.str()
    • getloc() == rhs_p.getloc()
    • gptr() - eback() == rhs_p.gptr() - rhs_p.eback()
    • egptr() - eback() == rhs_p.egptr() - rhs_p.eback()
    • pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()
    • epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()
  • Let rhs_a refer to the state of rhs just after this construction, the following expressions will evaluate to true:
    • !eback() || eback() != rhs_a.eback()
    • !gptr() || gptr() != rhs_a.gptr()
    • !egptr() || egptr() != rhs_a.egptr()
    • !pbase() || pbase() != rhs_a.pbase()
    • !pptr() || pptr() != rhs_a.pptr()
    • !epptr() || epptr() != rhs_a.epptr()
• 15) — The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible.

---

🎀 Parameters 🎀

• s — a std::basic_string used to initialize the buffer.
• t — an object (convertible to std::basic_string_view) used to initialize the buffer.
• a — another allocator used to construct the internal std::basic_string.
• rhs — another basic_stringbuf.
• which — specifies stream open mode. It is bitmask type, the following constants are defined:
  • app — seek to the end of stream before each write
  • binary — open in binary mode
  • in — open for reading
  • out — open for writing
  • trunc — discard the contents of the stream when opening
  • ate — seek to the end of stream immediately after open
  • noreplace (C++23) — open in exclusive mode

---

🫶 Notes 🫶

Typically called by the constructor of std::basic_stringstream.

The level of support for the open modes other than std::ios_base::in and std::ios_base::out varies among implementations. C++11 explicitly specifies the support for std::ios_base::ate in str() and in this constructor, but std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different effects on different implementations.

• Feature-test macro: __cpp_lib_sstream_from_string_view — value 202306L — standard (C++26) — feature: Interfacing string streams with std::string_view.

---

💖 Example 💖

Demonstrates calling the constructor of std::basic_stringbuf directly:

Run this code:

#include <iostream>
#include <sstream>

int main()
{
    // default constructor (mode = in | out)
    std::stringbuf buf1;
    buf1.sputc('1');
    std::cout << &buf1 << '\n';

    // string constructor in at-end mode (C++11)
    std::stringbuf buf2("test", std::ios_base::in
                              | std::ios_base::out
                              | std::ios_base::ate);
    buf2.sputc('1');
    std::cout << &buf2 << '\n';

    // append mode test (results differ among compilers)
    std::stringbuf buf3("test", std::ios_base::in
                              | std::ios_base::out
                              | std::ios_base::app);
    buf3.sputc('1');
    buf3.pubseekpos(1);
    buf3.sputc('2');
    std::cout << &buf3 << '\n';
}

Output:

1
test1
est12 (Sun Studio) 2st1 (GCC)

---

💀 Defect reports 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 432 — applied to C++98 — behavior as published: 1. overload (1) allocated no array object; 2. overload (3) did not specify how the input and output sequences are initialized. Correct behavior: 1. removed the limitation; 2. specified.
• LWG 562 — applied to C++98 — behavior as published: overload (3) set epptr() to point one past the last underlying character if bool(which & std::ios_base::out) == true. Correct behavior: epptr() can be set beyond that position.
• P0935R0 — applied to C++11 — behavior as published: the default constructor was explicit. Correct behavior: made implicit.

---

👑 See also 👑

• constructor — constructs the string stream (public member function of std::basic_stringstream<CharT,Traits,Allocator>).

---

okay bestie that’s the whole page 💖 source/version/date tea: http://cppreference.com, 2024.06.10, and the page is std::basic_...ic_stringbuf(3). byeee 🫶✨