29 Input/output library [input.output]

29.8 String-based streams [string.streams]

29.8.2 Class template basic_­stringbuf [stringbuf]

29.8.2.3 Member functions [stringbuf.members]

1
#
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
2
#
Effects: Initializes the input and output sequences from buf according to mode.
3
#
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.
4
#
[Note
:
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;
5
#
Returns: buf.get_­allocator().
🔗
basic_string<charT, traits, Allocator> str() const &;
6
#
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;
7
#
Constraints: SAlloc is a type that qualifies as an allocator ([container.requirements.general]).
8
#
Effects: Equivalent to: 
return basic_string<charT, traits, SAlloc>(view(), sa);
🔗
basic_string<charT, traits, Allocator> str() &&;
9
#
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().
10
#
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.
🔗
basic_string_view<charT, traits> view() const noexcept;
11
#
Let sv be basic_­string_­view<charT, traits>.
12
#
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.
13
#
[Note
:
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);
14
#
Effects: Equivalent to: 
buf = s;
init_buf_ptrs();
🔗
template<class SAlloc> void str(const basic_string<charT, traits, SAlloc>& s);
15
#
Constraints: is_­same_­v<SAlloc,Allocator> is false.
16
#
Effects: Equivalent to: 
buf = s;
init_buf_ptrs();
🔗
void str(basic_string<charT, traits, Allocator>&& s);
17
#
Effects: Equivalent to: 
buf = std::move(s);
init_buf_ptrs();