29 Input/output library [input.output]

29.6 Stream buffers [stream.buffers]

29.6.3 Class template basic_­streambuf [streambuf]

29.6.3.4 Virtual functions [streambuf.virtuals]

29.6.3.4.3 Get area [streambuf.virt.get]

đź”—
streamsize showmanyc();296
1
#
Returns: An estimate of the number of characters available in the sequence, or -1.
If it returns a positive value, then successive calls to underflow() will not return traits​::​eof() until at least that number of characters have been extracted from the stream.
If showmanyc() returns -1, then calls to underflow() or uflow() will fail.297
2
#
Default behavior: Returns zero.
3
#
Remarks: Uses traits​::​eof().
đź”—
streamsize xsgetn(char_type* s, streamsize n);
4
#
Effects: Assigns up to n characters to successive elements of the array whose first element is designated by s.
The characters assigned are read from the input sequence as if by repeated calls to sbumpc().
Assigning stops when either n characters have been assigned or a call to sbumpc() would return traits​::​eof().
5
#
Returns: The number of characters assigned.298
6
#
Remarks: Uses traits​::​eof().
đź”—
int_type underflow();
7
#
Remarks: The public members of basic_­streambuf call this virtual function only if gptr() is null or gptr() >= egptr().
8
#
Returns: traits​::​to_­int_­type(c), where c is the first character of the pending sequence, without moving the input sequence position past it.
If the pending sequence is null then the function returns traits​::​eof() to indicate failure.
9
#
The pending sequence of characters is defined as the concatenation of
  • (9.1)
    the empty sequence if gptr() is null, otherwise the characters in [gptr(), egptr()), followed by
  • (9.2)
    some (possibly empty) sequence of characters read from the input sequence.
10
#
The 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.
11
#
The backup sequence is the empty sequence if eback() is null, otherwise the characters in [eback(), gptr()).
12
#
Effects: The function sets up the gptr() and egptr() such that if the pending sequence is non-empty, then egptr() is non-null and the characters in [gptr(), egptr()) are the characters in the pending sequence, otherwise either gptr() is null or gptr() == egptr().
13
#
If eback() and gptr() are non-null then the function is not constrained as to their contents, but the “usual backup condition” is that either
  • (13.1)
    the backup sequence contains at least gptr() - eback() characters, in which case the characters in [eback(), gptr()) agree with the last gptr() - eback() characters of the backup sequence, or
  • (13.2)
    the characters in [gptr() - n, gptr()) agree with the backup sequence (where n is the length of the backup sequence).
14
#
Default behavior: Returns traits​::​eof().
đź”—
int_type uflow();
15
#
Preconditions: The constraints are the same as for underflow(), 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.
16
#
Default behavior: Calls underflow().
If underflow() returns traits​::​eof(), returns traits​::​eof().
Otherwise, returns the value of traits​::​to_­int_­type(*gptr()) and increment the value of the next pointer for the input sequence.
17
#
Returns: traits​::​eof() to indicate failure.
296)
The morphemes of showmanyc are “es-how-many-see”, not “show-manic”.
⮥
297)
underflow or uflow might fail by throwing an exception prematurely.
The intention is not only that the calls will not return eof() but that they will return “immediately”.
⮥
298)
Classes derived from basic_­streambuf can provide more efficient ways to implement xsgetn() and xsputn() by overriding these definitions from the base class.
⮥