std::basic_stringbuf::str(3)

NAME
std::basic_stringbuf::str - std::basic_stringbuf::str

Synopsis
   std::basic_string<CharT, Traits, Allocator> str() const; (until C++20)
   std::basic_string<CharT, Traits, Allocator> str() const&; (since C++20)
   template<class SAlloc>
   std::basic_string<CharT, Traits, SAlloc> str( const SAlloc& a (2) (since C++20)
   ) const;
   std::basic_string<CharT, Traits, Allocator> str() &&; (3) (since C++20)
   void str( const std::basic_string<CharT, Traits, Allocator>& s (1) (4)
   );
   template<class SAlloc> (5) (since C++20)
   void str( const std::basic_string<CharT, Traits, SAlloc>& s );
   void str( std::basic_string<CharT, Traits, Allocator>&& s ); (6) (since C++20)
   template< class StringViewLike > (7) (since C++26)
   void str( const StringViewLike& t );
   Gets and sets the underlying string.
   In the descriptions below, buf and mode are exposition-only data members of *this.
   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, (since C++20)
   Allocator>(view(), get_allocator());.
   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 Value Std Feature
   __cpp_lib_sstream_from_string_view 202306L (C++26) 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.
     DR Applied to Behavior as published Correct behavior
                      1. overload (1) did not specify the content
   LWG 432 C++98 of the underlying character sequence both specified
                      2. overload (4) did not specify how the
                      input and output sequences are initialized
                      overload (4) set epptr() to point one past
   LWG 562 C++98 the last underlying epptr() can be set
                      character if bool(mode & std::ios_base::out) beyond that position
                      == true

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