21 KiB
[streambuf.virtuals]
31 Input/output library [input.output]
31.6 Stream buffers [stream.buffers]
31.6.3 Class template basic_streambuf [streambuf]
31.6.3.5 Virtual functions [streambuf.virtuals]
31.6.3.5.1 Locales [streambuf.virt.locales]
void imbue(const locale&);
Effects: Change any translations based on locale.
Remarks: Allows the derived class to be informed of changes in locale at the time they occur.
Between invocations of this function a class derived from streambuf can safely cache results of calls to locale functions and to members of facets so obtained.
Default behavior: Does nothing.
31.6.3.5.2 Buffer management and positioning [streambuf.virt.buffer]
basic_streambuf* setbuf(char_type* s, streamsize n);
Effects: Influences stream buffering in a way that is defined separately for each class derived frombasic_streambuf in this Clause ([stringbuf.virtuals], [filebuf.virtuals]).
Default behavior: Does nothing.
Returnsthis.
pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived frombasic_streambuf in this Clause ([stringbuf.virtuals], [filebuf.virtuals]).
Default behavior: Returnspos_type(off_type(-1)).
pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out);
Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived frombasic_streambuf in this Clause ([stringbuf], [filebuf]).
Default behavior: Returnspos_type(off_type(-1)).
int sync();
Effects: Synchronizes the controlled sequences with the arrays.
That is, ifpbase() is non-null the characters betweenpbase() andpptr() are written to the controlled sequence.
The pointers may then be reset as appropriate.
Returns: -1 on failure.
What constitutes failure is determined by each derived class ([filebuf.virtuals]).
Default behavior: Returns zero.
31.6.3.5.3 Get area [streambuf.virt.get]
streamsize showmanyc();[267](#footnote-267 "The morphemes of showmanyc are âes-how-many-seeâ, not âshow-manicâ.")
Returns: An estimate of the number of characters available in the sequence, or â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.
Ifshowmanyc() returns â1, then calls tounderflow() oruflow() will fail.268
Default behavior: Returns zero.
Remarks: Usestraits::eof().
streamsize xsgetn(char_type* s, streamsize n);
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 tosbumpc().
Assigning stops when either n characters have been assigned or a call tosbumpc() would returntraits::eof().
Returns: The number of characters assigned.269
Remarks: Usestraits::eof().
int_type underflow();
Thepending sequence of characters is defined as the concatenation of
the empty sequence if gptr() is null, otherwise the characters in [gptr(), egptr()), followed by
some (possibly empty) sequence of characters read from the input sequence.
Theresult 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.
Thebackup sequence is the empty sequence if eback() is null, otherwise the characters in [eback(), gptr()).
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().
Ifeback() andgptr() are non-null then the function is not constrained as to their contents, but the âusual backup conditionâ is that either
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
the characters in [gptr() - n, gptr()) agree with the backup sequence (where n is the length of the backup sequence).
Returns: traits::to_int_type(c), where c is the firstcharacter of thepending sequence, without moving the input sequence position past it.
If the pending sequence is null then the function returnstraits::eof() to indicate failure.
Default behavior: Returnstraits::eof().
Remarks: The public members ofbasic_streambuf call this virtual function only ifgptr() is null orgptr() >= egptr().
int_type uflow();
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.
Default behavior: Callsunderflow().
Ifunderflow() returnstraits::eof(), returnstraits::eof().
Otherwise, returns the value oftraits::to_int_type(*gptr()) and increments the value of the next pointer for the input sequence.
Returns: traits::eof() to indicate failure.
The morphemes of showmanyc are âes-how-many-seeâ, not âshow-manicâ.
underflow oruflow can fail by throwing an exception prematurely.
The intention is not only that the calls will not returneof() but that they will return âimmediatelyâ.
Classes derived frombasic_streambuf can provide more efficient ways to implementxsgetn() andxsputn() by overriding these definitions from the base class.
31.6.3.5.4 Putback [streambuf.virt.pback]
int_type pbackfail(int_type c = traits::eof());
Thepending sequence is defined as forunderflow(), with the modifications that
-
Iftraits::eq_int_type(c, traits::eof()) returnstrue, then the input sequence is backed up one character before the pending sequence is determined.
-
Iftraits::eq_int_type(c, traits::eof()) returns false, then c is prepended. Whether the input sequence is backed up or modified in any other way is unspecified.
Postconditions: On return, the constraints ofgptr(),eback(), andpptr() are the same as forunderflow().
Returns: traits::eof() to indicate failure.
Failure may occur because the input sequence could not be backed up, or if for some other reason the pointers cannot be set consistent with the constraints.
pbackfail() is called only when put back has really failed.
Returns some value other thantraits::eof() to indicate success.
Default behavior: Returnstraits::eof().
Remarks: The public functions ofbasic_streambuf call this virtual function only whengptr() is null,gptr() == eback(), ortraits::eq(traits::to_char_type(c), gptr()[-1]) returnsfalse.
Other calls shall also satisfy that constraint.
31.6.3.5.5 Put area [streambuf.virt.put]
streamsize xsputn(const char_type* s, streamsize n);
Effects: Writes up to n characters to the output sequence as if by repeated calls tosputc(c).
The characters written are obtained from successive elements of the array whose first element is designated by s.
Writing stops when either n characters have been written or a call tosputc(c) would returntraits::eof().
It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means.
Returns: The number of characters written.
int_type overflow(int_type c = traits::eof());
Effects: Consumes some initial subsequence of the characters of thepending sequence.
The pending sequence is defined as the concatenation of
the empty sequence if pbase() is null, otherwise thepptr() - pbase() characters beginning atpbase(), followed by
the empty sequence iftraits::eq_int_type(c, traits::eof()) returnstrue, otherwise the sequence consisting of c.
Preconditions: Every overriding definition of this virtual function obeys the following constraints:
-
The effect of consuming a character on the associated output sequence is specified.270
-
Letr be the number of characters in the pending sequence not consumed. Ifr is nonzero thenpbase() andpptr() are set so that:pptr() - pbase() == r and the r characters starting atpbase() are the associated output stream. In case r is zero (all characters of the pending sequence have been consumed) then eitherpbase() is set tonullptr, orpbase() andpptr() are both set to the same non-null value.
-
The function may fail if either appending some character to the associated output stream fails or if it is unable to establishpbase() andpptr() according to the above rules.
Returns: traits::eof() or throws an exception if the function fails.
Otherwise, returns some value other thantraits::eof() to indicate success.271
Default behavior: Returnstraits::eof().
Remarks: The member functionssputc() andsputn() call this function in case that no room can be found in the put buffer enough to accommodate the argument character sequence.
That is, for each class derived from a specialization ofbasic_streambuf in this Clause ([stringbuf], [filebuf]), a specification of how consuming a character effects the associated output sequence is given.
There is no requirement on a program-defined class.
Typically,overflow returns c to indicate success, except whentraits::eq_int_type(c, traits::eof()) returnstrue, in which case it returnstraits::not_eof(c).