cppdraft_translate/cppdraft/streambuf/virt/get.md

[streambuf.virt.get]

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

## 31.6 Stream buffers [[stream.buffers]](stream.buffers#streambuf.virt.get)

### 31.6.3 Class template basic_streambuf [[streambuf]](streambuf#virt.get)

#### 31.6.3.5 Virtual functions [[streambuf.virtuals]](streambuf.virtuals#streambuf.virt.get)

#### 31.6.3.5.3 Get area [streambuf.virt.get]

[🔗](#lib:showmanyc,basic_streambuf)

`streamsize showmanyc();[267](#footnote-267 "The morphemes of showmanyc are “es-how-many-see”, not “show-manic”.")
`

[1](#1)

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

*Returns*: An estimate of the number of
characters available in the sequence, or −1[.](#1.sentence-1)

If it returns
a positive value, then successive calls tounderflow() will not returntraits​::​eof() until at least that number of characters have been
extracted from the stream[.](#1.sentence-2)

Ifshowmanyc() returns −1, then calls tounderflow() oruflow() will fail[.](#1.sentence-3)[268](#footnote-268 "underflow or uflow can fail by throwing an exception prematurely. The intention is not only that the calls will not return eof() but that they will return “immediately”.")

[2](#2)

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

*Default behavior*: Returns zero[.](#2.sentence-1)

[3](#3)

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

*Remarks*: Usestraits​::​eof()[.](#3.sentence-1)

[🔗](#lib:xsgetn,basic_streambuf)

`streamsize xsgetn(char_type* s, streamsize n);
`

[4](#4)

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

*Effects*: Assigns up to n characters to successive elements of
the array whose first element is designated by s[.](#4.sentence-1)

The characters assigned are read from the input sequence as if
by repeated calls tosbumpc()[.](#4.sentence-2)

Assigning stops when either n characters
have been assigned or a call tosbumpc() would returntraits​::​eof()[.](#4.sentence-3)

[5](#5)

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

*Returns*: The number of characters assigned[.](#5.sentence-1)[269](#footnote-269 "Classes derived from basic_­streambuf can provide more efficient ways to implement xsgetn() and xsputn() by overriding these definitions from the base class.")

[6](#6)

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

*Remarks*: Usestraits​::​eof()[.](#6.sentence-1)

[🔗](#lib:underflow,basic_streambuf)

`int_type underflow();
`

[7](#7)

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

The[*pending sequence*](#def:pending_sequence) of characters is defined as the concatenation of

- [(7.1)](#7.1)

the empty sequence if gptr() is null, otherwise the
characters in
[gptr(), egptr()),
followed by

- [(7.2)](#7.2)

some (possibly empty) sequence of characters read from the input sequence[.](#7.sentence-1)

[8](#8)

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

The[*result character*](#def:result_character) is
the first character of the pending sequence if it is non-empty,
otherwise
the next character that would be read from the input sequence[.](#8.sentence-1)

[9](#9)

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

The[*backup sequence*](#def:backup_sequence) is the empty sequence if eback() is null, otherwise the
characters in
[eback(), gptr())[.](#9.sentence-1)

[10](#10)

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

*Effects*: The function sets up thegptr() andegptr() such that
if the pending sequence is non-empty, thenegptr() is non-null and
the characters in [gptr(), egptr()) are
the characters in the pending sequence,
otherwise
either gptr() is null orgptr() == egptr()[.](#10.sentence-1)

[11](#11)

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

Ifeback() andgptr() are non-null then the function is not constrained as to their contents, but the “usual backup condition” is that either

- [(11.1)](#11.1)

the backup sequence contains at leastgptr() - eback() characters, in which case the characters in
[eback(), gptr())
agree with the lastgptr() - eback() characters of the backup sequence, or

- [(11.2)](#11.2)

the characters in [gptr() - n, gptr())
agree with the backup sequence (where n is the length of the backup sequence)[.](#11.sentence-1)

[12](#12)

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

*Returns*: traits​::​to_int_type(c),
where c is the first*character* of the[*pending sequence*](#def:pending_sequence),
without moving the input sequence position past it[.](#12.sentence-1)

If the pending sequence is null then the function returnstraits​::​eof() to indicate failure[.](#12.sentence-2)

[13](#13)

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

*Default behavior*: Returnstraits​::​eof()[.](#13.sentence-1)

[14](#14)

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

*Remarks*: The public members ofbasic_streambuf call this virtual function only ifgptr() is null orgptr() >= egptr()[.](#14.sentence-1)

[🔗](#lib:uflow,basic_streambuf)

`int_type uflow();
`

[15](#15)

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

*Preconditions*: The constraints are the same as forunderflow(),
except that the result character is transferred from the pending
sequence to the backup sequence, and the pending sequence is not empty before the transfer[.](#15.sentence-1)

[16](#16)

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

*Default behavior*: Callsunderflow()[.](#16.sentence-1)

Ifunderflow() returnstraits​::​eof(),
returnstraits​::​eof()[.](#16.sentence-2)

Otherwise, returns the value oftraits​::​to_int_type(*gptr()) and increments the value of the next pointer for the input sequence[.](#16.sentence-3)

[17](#17)

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

*Returns*: traits​::​eof() to indicate failure[.](#17.sentence-1)

[267)](#footnote-267)[267)](#footnoteref-267)

The morphemes of showmanyc are “es-how-many-see”, not “show-manic”[.](#footnote-267.sentence-1)

[268)](#footnote-268)[268)](#footnoteref-268)

underflow oruflow can fail by throwing an exception prematurely[.](#footnote-268.sentence-1)

The intention is not only that the calls will not returneof() but that they will return “immediately”[.](#footnote-268.sentence-2)

[269)](#footnote-269)[269)](#footnoteref-269)

Classes derived frombasic_streambuf can provide more efficient ways to implementxsgetn() andxsputn() by overriding these definitions from the base class[.](#footnote-269.sentence-1)