31 Input/output library [input.output]

31.8 String-based streams [string.streams]

31.8.2 Class template basic_stringbuf [stringbuf]

31.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:

(3.1)
If ios_base::out is set in mode, pbase() points to buf.front() and epptr() >= pbase() + buf.size() is true;
- (3.1.1)
  in addition, if ios_base::ate is set in mode, pptr() == pbase() + buf.size() is true,
- (3.1.2)
  otherwise pptr() == pbase() is true.
(3.2)
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 can 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.reqmts]).

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:

(12.1)
If ios_base::out is set in mode, then sv(pbase(), high_mark-pbase()) is returned.
(12.2)
Otherwise, if ios_base::in is set in mode, then sv(eback(), egptr()-eback()) is returned.
(12.3)
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();

🔗

template<class T>
  void str(const T& t);

Constraints: is_convertible_v<const T&, basic_string_view<charT, traits>> is true.

Effects: Equivalent to: basic_string_view<charT, traits> sv = t; buf = sv; init-buf-ptrs();