[stringbuf.members] (original) (raw)

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_stringbufpassing 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() andepptr() >= 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 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 bufensure 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;

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 andpbase(), 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 *thisis 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();