# std::basic_stringbuf<CharT,Traits,Allocator>::str

From cppreference.com
< cpp‎ | io‎ | basic stringbuf

| (1) |
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 ) const; | (2) | (since C++20)
std::basic_string<CharT, Traits, Allocator> str() &&; | (3) | (since C++20)
void str( const std::basic_string<CharT, Traits, Allocator>& s ); | (4) |
template<class SAlloc> void str( const std::basic_string<CharT, Traits, SAlloc>& s ); | (5) | (since C++20)
void str( std::basic_string<CharT, Traits, Allocator>&& s ); | (6) | (since C++20)

Gets and sets the underlying string.

For the purpose of explanation, let mode denote the open mode of the stream and buf_ denote the internal std::basic_string object holding the underlying character sequence. Define buffer pointer initialization as follows:

- For input streams (bool(mode & std::ios_base::in) == true), makes eback() point at the first character, gptr() == eback(), and egptr() == eback() + buf_.size(): the subsequent input will read the first character of the string.
- For output streams (bool(mode & std::ios_base::out) == true), makes pbase() points at the first character and epptr() >= pbase() + buf_.size() (epptr() is allowed to point farther so that the following sputc() would not immediately call overflow()).

  - For append streams (bool(mode & std::ios_base::ate) == true), makes pptr() == pbase() + buf_.size(), so that subsequent output will be appended to the last character of the string.
  - For non-appending output streams, makes pptr() == pbase(), so that subsequent output will overwrite the characters of the string.

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 std::basic_string object as if initialized with std::move(buf_). buf_ may need to be adjusted to contain the same content as in (1) at first. After construction of the std::basic_string object, sets buf_ to empty and performs buffer pointer initialization, then returns the std::basic_string object.
4) Replaces the underlying character sequence as if by buf_ = s, then performs buffer pointer initialization.
5) Same as (4), except the type of s's allocator is not `Allocator`. This overload participates in overload resolution only if `SAlloc` and `Allocator` are not the same type.
6) Replaces the underlying character sequence as if by buf_ = std::move(s), then performs buffer pointer initialization.

### Parameters

s | - | a std::basic_string object 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-6) (none)

### Notes

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

### 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
--- | --- | --- | ---
LWG 432 | C++98 | 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 | both specified
LWG 562 | C++98 | overload (4) set epptr() to point one past the last underlying character if bool(mode & std::ios_base::out) == true | epptr() can be set beyond that position
LWG 1448 | C++98 | buffer pointer initialization made pptr() == pbase() + buf_.data() for streams that are both input and output streams | makes pptr() == pbase() + buf_.size() for append streams

### 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)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/io/basic_stringbuf/str&oldid=156258"