cppdraft_translate/cppdraft/stringbuf/virtuals.md

[stringbuf.virtuals]

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

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

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

#### 31.8.2.5 Overridden virtual functions [stringbuf.virtuals]

[🔗](#lib:underflow,basic_stringbuf)

`int_type underflow() override;
`

[1](#1)

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

*Returns*: If the input sequence has a read position available,
returnstraits​::​to_int_type(*gptr())[.](#1.sentence-1)

Otherwise, returnstraits​::​eof()[.](#1.sentence-2)

Any character in the underlying buffer which has been initialized is considered
to be part of the input sequence[.](#1.sentence-3)

[🔗](#lib:pbackfail,basic_stringbuf)

`int_type pbackfail(int_type c = traits::eof()) override;
`

[2](#2)

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

*Effects*: Puts back the character designated by c to the input
sequence, if possible, in one of three ways:

- [(2.1)](#2.1)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and
if the input sequence has a putback position available, and
iftraits​::​eq(to_char_type(c), gptr()[-1]) returnstrue,
assignsgptr() - 1 togptr()[.](#2.1.sentence-1)
  Returns:c[.](#2.1.sentence-2)

- [(2.2)](#2.2)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and if the input sequence
has a putback position available, and
if *mode*&ios_base​::​out is
nonzero,
assigns c to*--gptr()[.](#2.2.sentence-1)
  Returns:c[.](#2.2.sentence-2)

- [(2.3)](#2.3)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnstrue and if the input sequence has a putback position available,
assignsgptr() - 1 togptr()[.](#2.3.sentence-1)
  Returns:traits​::​not_eof(c)[.](#2.3.sentence-2)

[3](#3)

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

*Returns*: As specified above, ortraits​::​eof() to indicate failure[.](#3.sentence-1)

[4](#4)

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

*Remarks*: If the function can succeed in more than one of these ways, it is
unspecified which way is chosen[.](#4.sentence-1)

[🔗](#lib:overflow,basic_stringbuf)

`int_type overflow(int_type c = traits::eof()) override;
`

[5](#5)

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

*Effects*: Appends the character designated by c to the output
sequence, if possible, in one of two ways:

- [(5.1)](#5.1)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and if either
the output sequence has a write position available or
the function makes a write position available
(as described below),
the function callssputc(c)[.](#5.1.sentence-1)
  Signals success by returning c[.](#5.1.sentence-2)

- [(5.2)](#5.2)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnstrue,
there is no character to append[.](#5.2.sentence-1)
  Signals success by returning a value other thantraits​::​eof()[.](#5.2.sentence-2)

[6](#6)

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

*Returns*: As specified above, ortraits​::​eof() to indicate failure[.](#6.sentence-1)

[7](#7)

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

*Remarks*: The function can alter the number of write positions available as a
result of any call[.](#7.sentence-1)

[8](#8)

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

The function can make a write position available only ifios_base​::​out is set in *mode*[.](#8.sentence-1)

To make a write position available,
the function reallocates (or initially allocates) an array object
with a sufficient number of elements to hold
the current array object (if any), plus
at least
one additional write position[.](#8.sentence-2)

If ios_base​::​in is set in *mode*,
the function alters the read end pointeregptr() to point just past the new write position[.](#8.sentence-3)

[🔗](#lib:seekoff,basic_stringbuf)

`pos_type seekoff(off_type off, ios_base::seekdir way,
                 ios_base::openmode which
                   = ios_base::in | ios_base::out) override;
`

[9](#9)

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

*Effects*: Alters the stream position within one of the
controlled sequences, if possible, as indicated in Table [144](#tab:stringbuf.seekoff.pos "Table 144: seekoff positioning")[.](#9.sentence-1)

Table [144](#tab:stringbuf.seekoff.pos) — seekoff positioning [[tab:stringbuf.seekoff.pos]](./tab:stringbuf.seekoff.pos)  

| [🔗](#tab:stringbuf.seekoff.pos-row-1)<br>**Conditions** | **Result** |
| --- | --- |
| [🔗](#tab:stringbuf.seekoff.pos-row-2)<br>ios_base​::​in is set in which | positions the input sequence |
| [🔗](#tab:stringbuf.seekoff.pos-row-3)<br>ios_base​::​out is set in which | positions the output sequence |
| [🔗](#tab:stringbuf.seekoff.pos-row-4)<br>both ios_base​::​in and ios_base​::​out are set in which and either   way == ios_base​::​beg or   way == ios_base​::​end | positions both the input and the output sequences |
| [🔗](#tab:stringbuf.seekoff.pos-row-5)<br>Otherwise | the positioning operation fails[.](#tab:stringbuf.seekoff.pos-row-5-column-2-sentence-1) |

[10](#10)

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

For a sequence to be positioned,
the function determines newoff as indicated in
Table [145](#tab:stringbuf.seekoff.newoff "Table 145: newoff values")[.](#10.sentence-1)

If the sequence's next pointer
(eithergptr() orpptr())
is a null pointer and newoff is nonzero,
the positioning operation fails[.](#10.sentence-2)

Table [145](#tab:stringbuf.seekoff.newoff) — newoff values [[tab:stringbuf.seekoff.newoff]](./tab:stringbuf.seekoff.newoff)  

| [🔗](#tab:stringbuf.seekoff.newoff-row-1)<br>**Condition** | **newoff Value** |
| --- | --- |
| [🔗](#tab:stringbuf.seekoff.newoff-row-2)<br>way == ios_base​::​beg | 0 |
| [🔗](#tab:stringbuf.seekoff.newoff-row-3)<br>way == ios_base​::​cur | the next pointer minus the beginning pointer (xnext - xbeg)[.](#tab:stringbuf.seekoff.newoff-row-3-column-2-sentence-1) |
| [🔗](#tab:stringbuf.seekoff.newoff-row-4)<br>way == ios_base​::​end | the high mark pointer minus the beginning pointer (high_mark - xbeg)[.](#tab:stringbuf.seekoff.newoff-row-4-column-2-sentence-1) |

[11](#11)

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

If(newoff + off) < 0,
or if newoff + off refers to an uninitialized
character ([[stringbuf.members]](stringbuf.members "31.8.2.4 Member functions")),
the positioning operation fails[.](#11.sentence-1)

Otherwise, the function assignsxbeg + newoff + off to the next pointer xnext[.](#11.sentence-2)

[12](#12)

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

*Returns*: pos_type(newoff),
constructed from the resultant offset newoff (of typeoff_type),
that stores the resultant stream position, if possible[.](#12.sentence-1)

If the positioning operation fails, or
if the constructed object cannot represent the resultant stream position,
the return value ispos_type(off_type(-1))[.](#12.sentence-2)

[🔗](#lib:seekpos,basic_stringbuf)

`pos_type seekpos(pos_type sp,
                 ios_base::openmode which
                   = ios_base::in | ios_base::out) override;
`

[13](#13)

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

*Effects*: Equivalent to seekoff(off_type(sp), ios_base​::​beg, which)[.](#13.sentence-1)

[14](#14)

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

*Returns*: sp to indicate success, orpos_type(off_type(-1)) to indicate failure[.](#14.sentence-1)

[🔗](#lib:setbuf,basic_streambuf)

`basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
`

[15](#15)

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

*Effects*: implementation-defined,
except thatsetbuf(0, 0) has no effect[.](#15.sentence-1)

[16](#16)

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

*Returns*: this[.](#16.sentence-1)