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)