# std::basic_stringbuf::str

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

std::basic_string<CharT, Traits, Allocator> str() const; | (1) |
void str( const std::basic_string<CharT, Traits, Allocator>& s); | (2) |

Gets and sets the underlying 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 the second overload of `str()`, or from an 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

(since C++11)

2) Deletes the entire underlying character sequence of this `std::basic_stringbuf` and then configures a new underlying character sequence containing a copy of the contents of `s`. The pointers of std::basic_streambuf are initialized as follows:

- For input streams (mode & ios_base::in == true), eback() points at the first character, gptr() == eback(), and egptr() == eback() + s.size(): the subsequent input will read the first character copied from `s`.
- For output streams (mode & ios_base::out == true), pbase() points at the first character and epptr() >= pbase() + s.size() (epptr is allowed to point farther so that the following `sputc()` wouldn't immediately call `overflow()`)
  - For append streams (mode & ios_base::ate == true), pptr() == pbase() + s.size(), so that subsequent output will be appended to the last character copied from `s` (since C++11)
  - For non-appending output streams, pptr() == pbase(), so that subsequent output will overwrite the characters copied from `s`.

### Parameters

s | - | a string object holding the replacement character sequence

### Return value

1) A string object holding a copy of this buffer's underlying character sequence.
2) (none)

### Notes

This function is typically accessed through std::basic_stringstream::str().

### Example

Run this code

    #include <sstream>
    #include <iostream>
    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"

### See also

str | gets or sets the contents of underlying string device object (public member function of `std::basic_stringstream`)

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