29 Input/output library [input.output]

29.8 String-based streams [string.streams]

29.8.2 Class template basic_­stringbuf [stringbuf]

29.8.2.4 Member functions [stringbuf.members]

The member functions getting the underlying character sequence all refer to a high_­mark value, where high_­mark represents the position one past the highest initialized character in the buffer.
Characters can be initialized by writing to the stream, by constructing the basic_­stringbuf passing a basic_­string argument, or by calling one of the str member functions passing a basic_­string as an argument.
In the latter case, all characters initialized prior to the call are now considered uninitialized (except for those characters re-initialized by the new basic_­string).
void init_buf_ptrs(); // exposition only
Effects: Initializes the input and output sequences from buf according to mode.
Postconditions:
  • If ios_­base​::​out is set in mode, pbase() points to buf.front() and epptr() >= pbase() + buf.size() is true;
    • in addition, if ios_­base​::​ate is set in mode, pptr() == pbase() + buf.size() is true,
    • otherwise pptr() == pbase() is true.
  • If ios_­base​::​in is set in mode, eback() points to buf.front(), and (gptr() == eback() && egptr() == eback() + buf.size()) is true.
[Note 1:
For efficiency reasons, stream buffer operations might violate invariants of buf while it is held encapsulated in the basic_­stringbuf, e.g., by writing to characters in the range [buf.data() + buf.size(), buf.data() + buf.capacity()).
All operations retrieving a basic_­string from buf ensure that the basic_­string invariants hold on the returned value.
— end note]
allocator_type get_allocator() const noexcept;
Returns: buf.get_­allocator().
basic_string<charT, traits, Allocator> str() const &;
Effects: Equivalent to: return basic_string<charT, traits, Allocator>(view(), get_allocator());
template<class SAlloc> basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
Constraints: SAlloc is a type that qualifies as an allocator ([container.requirements.general]).
Effects: Equivalent to: return basic_string<charT, traits, SAlloc>(view(), sa);
basic_string<charT, traits, Allocator> str() &&;
Postconditions: The underlying character sequence buf is empty and pbase(), pptr(), epptr(), eback(), gptr(), and egptr() are initialized as if by calling init_­buf_­ptrs() with an empty buf.
Returns: A basic_­string<charT, traits, Allocator> object move constructed from the basic_­stringbuf's underlying character sequence in buf.
This can be achieved by first adjusting buf to have the same content as view().
basic_string_view<charT, traits> view() const noexcept;
Let sv be basic_­string_­view<charT, traits>.
Returns: A sv object referring to the basic_­stringbuf's underlying character sequence in buf:
  • If ios_­base​::​out is set in mode, then sv(pbase(), high_­mark-pbase()) is returned.
  • Otherwise, if ios_­base​::​in is set in mode, then sv(eback(), egptr()-eback()) is returned.
  • Otherwise, sv() is returned.
[Note 2:
Using the returned sv object after destruction or invalidation of the character sequence underlying *this is undefined behavior, unless sv.empty() is true.
— end note]
void str(const basic_string<charT, traits, Allocator>& s);
Effects: Equivalent to: buf = s; init_buf_ptrs();
template<class SAlloc> void str(const basic_string<charT, traits, SAlloc>& s);
Constraints: is_­same_­v<SAlloc,Allocator> is false.
Effects: Equivalent to: buf = s; init_buf_ptrs();
void str(basic_string<charT, traits, Allocator>&& s);
Effects: Equivalent to: buf = std::move(s); init_buf_ptrs();