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

From cppreference.com
< cpp‎ | io‎ | basic stringbuf
 
C++
 
Input/output library
I/O manipulators
C-style I/O
Buffers
(C++23)
(deprecated in C++98)
(C++20)
Streams
Abstractions
File I/O
String I/O
Array I/O
(C++23)
(C++23)
(C++23)
(deprecated in C++98)
(deprecated in C++98)
(deprecated in C++98)
Synchronized Output
(C++20)
Types
Error category interface
(C++11)
(C++11)
 
std::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 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() wouldn't 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.
(since C++11)
  • 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 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)

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 basic_string object holding the replacement character sequence
a - allocator to use for all memory allocations of the returned basic_string

Return value

1-3) A 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 <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

 gets or sets the contents of underlying string device object
(public member function of std::basic_stringstream<CharT,Traits,Allocator>)
(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=116747"