[stringbuf.members]

# 31 Input/output library [[input.output]](./#input.output)

## 31.8 String-based streams [[string.streams]](string.streams#stringbuf.members)

### 31.8.2 Class template basic_stringbuf [[stringbuf]](stringbuf#members)

#### 31.8.2.4 Member functions [stringbuf.members]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8392)

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[.](#1.sentence-1)

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[.](#1.sentence-2)

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)[.](#1.sentence-3)

[🔗](#itemdecl:1)

`void init-buf-ptrs();
`

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8411)

*Effects*: Initializes the input and output sequences from *buf* according to *mode*[.](#2.sentence-1)

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8416)

*Postconditions*: 

- [(3.1)](#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)](#3.1.1)

in addition, if ios_base​::​ate is set in *mode*, pptr() == pbase() + *buf*.size() is true,

  * [(3.1.2)](#3.1.2)

otherwise pptr() == pbase() is true[.](#3.1.sentence-1)

- [(3.2)](#3.2)

  If ios_base​::​in is set in *mode*, eback() points to *buf*.front(), and (gptr() == eback() && egptr() == eback() + *buf*.size()) is true[.](#3.2.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8433)

[*Note [1](#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())[.](#4.sentence-1)

All operations retrieving a basic_string from buf ensure that the basic_string invariants hold on the returned value[.](#4.sentence-2)

— *end note*]

[🔗](#lib:get_allocator,basic_stringbuf)

`allocator_type get_allocator() const noexcept;
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8451)

*Returns*: *buf*.get_allocator()[.](#5.sentence-1)

[🔗](#lib:str,basic_stringbuf)

`basic_string<charT, traits, Allocator> str() const &;
`

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8462)

*Effects*: Equivalent to:return basic_string<charT, traits, Allocator>(view(), get_allocator());

[🔗](#lib:str,basic_stringbuf_)

`template<class SAlloc>
  basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
`

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8477)

*Constraints*: SAlloc is a type that
qualifies as an allocator ([[container.reqmts]](container.reqmts "23.2.2.2 Container requirements"))[.](#7.sentence-1)

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8482)

*Effects*: Equivalent to:return basic_string<charT, traits, SAlloc>(view(), sa);

[🔗](#itemdecl:5)

`basic_string<charT, traits, Allocator> str() &&;
`

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8495)

*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[.](#9.sentence-1)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8503)

*Returns*: A basic_string<charT, traits, Allocator> object
move constructed from
the basic_stringbuf's underlying character sequence in buf[.](#10.sentence-1)

This can be achieved by first adjusting buf to have
the same content as view()[.](#10.sentence-2)

[🔗](#lib:view,basic_stringbuf)

`basic_string_view<charT, traits> view() const noexcept;
`

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8518)

Let sv be basic_string_view<charT, traits>[.](#11.sentence-1)

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8521)

*Returns*: A sv object referring to
the basic_stringbuf's underlying character sequence in buf:

- [(12.1)](#12.1)

  If ios_base​::​out is set in *mode*,
 then sv(pbase(), high_mark - pbase()) is returned[.](#12.1.sentence-1)

- [(12.2)](#12.2)

  Otherwise, if ios_base​::​in is set in *mode*,
 then sv(eback(), egptr() - eback()) is returned[.](#12.2.sentence-1)

- [(12.3)](#12.3)

  Otherwise, sv() is returned[.](#12.3.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8533)

[*Note [2](#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[.](#13.sentence-1)

— *end note*]

[🔗](#lib:str,basic_stringbuf__)

`void str(const basic_string<charT, traits, Allocator>& s);
`

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8547)

*Effects*: Equivalent to:*buf* = s;*init-buf-ptrs*();

[🔗](#lib:str,basic_stringbuf___)

`template<class SAlloc>
  void str(const basic_string<charT, traits, SAlloc>& s);
`

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8563)

*Constraints*: is_same_v<SAlloc, Allocator> is false[.](#15.sentence-1)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8567)

*Effects*: Equivalent to:*buf* = s;*init-buf-ptrs*();

[🔗](#lib:str,basic_stringbuf____)

`void str(basic_string<charT, traits, Allocator>&& s);
`

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8582)

*Effects*: Equivalent to:*buf* = std::move(s);*init-buf-ptrs*();

[🔗](#lib:str,basic_stringbuf_____)

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

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8598)

*Constraints*: is_convertible_v<const T&, basic_string_view<charT, traits>> is true[.](#18.sentence-1)

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L8603)

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