std::basic_stringbuf::str(3)

okay so bestie 💖 welcome to the std::basic_stringbuf::str(3) page, straight out of the C++ Standard Libary — yes, that exact spelling, we're keeping it. This is the whole str situation for std::basic_stringbuf: getting the underlying string and setting it, with all the overloads and caveats. Buckle up 🎀

🌸 NAME 🌸

std::basic_stringbuf::str — std::basic_stringbuf::str

✨ Synopsis ✨

Here's the overload lineup, bestie — same signatures, same conditions, no cap:

• (1) std::basic_string<CharT, Traits, Allocator> str() const; — (until C++20)
• (1) std::basic_string<CharT, Traits, Allocator> str() const&; — (since C++20)
• (2) (since C++20) — template<class SAlloc> std::basic_string<CharT, Traits, SAlloc> str( const SAlloc& a ) const;
• (3) (since C++20) — std::basic_string<CharT, Traits, Allocator> str() &&;
• (4) — void str( const std::basic_string<CharT, Traits, Allocator>& s );
• (5) (since C++20) — template<class SAlloc> void str( const std::basic_string<CharT, Traits, SAlloc>& s );
• (6) (since C++20) — void str( std::basic_string<CharT, Traits, Allocator>&& s );
• (7) (since C++26) — template< class StringViewLike > void str( const StringViewLike& t );

In the descriptions below, buf and mode are exposition-only data members of *this. iykyk 🫶

This function gets and sets the underlying string. Literally its whole job.

1. Creates and returns a std::basic_string object containing a copy of this std::basic_stringbuf's underlying character sequence. For input-only streams, the returned string contains the characters from the range [eback(), egptr()). For input/output or output-only streams, contains the characters from pbase() to the last character in the sequence regardless of egptr() and epptr().

The member character sequence in a buffer open for writing can be over-allocated for efficiency purposes. In that case, only the initialized characters are returned: these characters are the ones that were obtained from the string argument of the constructor, the string argument of the most recent call to a setter overload of str(), or from a write operation. A typical implementation that uses over-allocation maintains a high-watermark pointer to track the end of the initialized part of the buffer and this overload returns the characters from pbase() to the high-watermark pointer.

Equivalent to return std::basic_string<CharT, Traits, Allocator>(view(), get_allocator());. (since C++20)

2. Same as (1), except that a is used to construct the returned std::basic_string. Equivalent to return std::basic_string<CharT, Traits, SAlloc>(view(), a);. This overload participates in overload resolution only if SAlloc meets the requirements of Allocator.
3. Creates a std::basic_string object as if by move constructing it from *this's underlying character sequence in buf. buf may need to be adjusted to contain the same content as in (1) at first. After that, sets buf to empty and calls init_buf_ptrs(), then returns the std::basic_string object.
4. Replaces the underlying character sequence as if by buf = s, then calls init_buf_ptrs().
5. Same as (4), except the type of s's allocator is not Allocator. This overload participates in overload resolution only if std::is_same_v<SAlloc, Allocator> is false.
6. Replaces the underlying character sequence as if by buf = std::move(s), then calls init_buf_ptrs().
7. Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then replaces the underlying character sequence as if by buf = sv, then calls init_buf_ptrs().

This overload participates in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true.

🎀 Parameters 🎀

• s — a std::basic_string object holding the replacement character sequence
• t — an object (convertible to std::basic_string_view) holding the replacement character sequence
• a — allocator to use for all memory allocations of the returned std::basic_string

💜 Return value 💜

• 1–3) A std::basic_string object holding this buffer's underlying character sequence.
• 4–7) (none)

🌈 Notes 🌈

This function is typically accessed through std::basic_istringstream::str(), std::basic_ostringstream::str(), or std::basic_stringstream::str().

Feature-test macro moment ⭐:

• __cpp_lib_sstream_from_string_view — value 202306L, std (C++26), feature: Interfacing string streams with std::string_view

🦋 Example 🦋

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    int n;

    std::istringstream in;  // could also use in("1 2")
    in.rdbuf()->str("1 2"); // set the get area
    in >> n;
    std::cout << "after reading the first int from \"1 2\", the int is "
              << n << ", str() = \"" << in.rdbuf()->str() << "\"\n"; // or in.str()

    std::ostringstream out("1 2");
    out << 3;
    std::cout << "after writing the int '3' to output stream \"1 2\""
              << ", str() = \"" << out.str() << "\"\n";

    std::ostringstream ate("1 2", std::ios_base::ate); // C++11
    ate << 3;
    std::cout << "after writing the int '3' to append stream \"1 2\""
              << ", str() = \"" << ate.str() << "\"\n";
}

⭐ Output ⭐

after reading the first int from "1 2", the int is 1, str() = "1 2"
after writing the int '3' to output stream "1 2", str() = "3 2"
after writing the int '3' to append stream "1 2", str() = "1 23"

💀 Defect reports 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. Not me reading the lore 💅

• DR LWG 432, applied to C++98 — behavior as published: 1. overload (1) did not specify the content of the underlying character sequence; 2. overload (4) did not specify how the input and output sequences are initialized. Correct behavior: both specified.
• DR LWG 562, applied to C++98 — behavior as published: overload (4) set epptr() to point one past the last underlying character if bool(mode & std::ios_base::out) == true. Correct behavior: epptr() can be set beyond that position.

👑 See also 👑

• str — gets or sets the contents of underlying string device object; public member function of std::basic_stringstream<CharT,Traits,Allocator>
• view (C++20) — obtains a view over the underlying character sequence; public member function

---

source/version: http://cppreference.com · date: 2024.06.10 · page: std::basic_stringbuf::str(3) — byeee bestie, go slay those string streams 💅✨🫶