void imbue(const 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.
basic_streambuf* setbuf(char_type* s, streamsize n);
pos_type seekoff(off_type off, ios_base::seekdir way,
= ios_base::in | ios_base::out);
pos_type seekpos(pos_type sp,
= ios_base::in | ios_base::out);
Effects: Synchronizes the controlled sequences with the arrays. That is, if pbase() is non-null the characters between pbase() and pptr() are written to the controlled sequence. The pointers may then be reset as appropriate.
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.301
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 to sbumpc(). Assigning stops when either n characters have been assigned or a call to sbumpc() would return traits::eof().
Remarks: The public members of basic_streambuf call this virtual function only if gptr() is null or gptr() >= egptr()
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.
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.
The backup sequence is the empty sequence if eback() is null, otherwise the characters in [eback(), gptr()).
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().
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
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
the characters in [gptr() - n, gptr()) agree with the backup sequence (where n is the length of the backup sequence).
Requires: The constraints are the same as for underflow(), except that the result character shall be transferred from the pending sequence to the backup sequence, and the pending sequence shall not be empty before the transfer.
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.
The morphemes of showmanyc are “es-how-many-see”, not “show-manic”.
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”.
Classes derived from basic_streambuf can provide more efficient ways to implement xsgetn() and xsputn() by overriding these definitions from the base class.
int_type pbackfail(int_type c = traits::eof());
Remarks: The public functions of basic_streambuf call this virtual function only when gptr() is null, gptr() == eback(), or traits::eq(traits::to_char_type(c), gptr()[-1]) returns false. Other calls shall also satisfy that constraint.
The pending sequence is defined as for underflow(), with the modifications that
If traits::eq_int_type(c, traits::eof()) returns true, then the input sequence is backed up one character before the pending sequence is determined.
If traits::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 of gptr(), eback(), and pptr() are the same as for underflow().
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 could not be set consistent with the constraints. pbackfail() is called only when put back has really failed.
streamsize xsputn(const char_type* s, streamsize n);
Effects: Writes up to n characters to the output sequence as if by repeated calls to sputc(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 to sputc(c) would return traits::eof(). It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means.
int_type overflow(int_type c = traits::eof());
Effects: Consumes some initial subsequence of the characters of the pending sequence. The pending sequence is defined as the concatenation of
the empty sequence if pbase() is not null, otherwise the pptr() - pbase() characters beginning at pbase(), followed by
the empty sequence if traits::eq_int_type(c, traits::eof()) returns true, otherwise the sequence consisting of c.
Remarks: The member functions sputc() and sputn() call this function in case that no room can be found in the put buffer enough to accommodate the argument character sequence.
Requires: Every overriding definition of this virtual function shall obey the following constraints:
2.Let r be the number of characters in the pending sequence not consumed. If r is nonzero then pbase() and pptr() shall be set so that: pptr() - pbase() == r and the r characters starting at pbase() are the associated output stream. In case r is zero (all characters of the pending sequence have been consumed) then either pbase() is set to nullptr, or pbase() and pptr() are both set to the same non-null value.
3.The function may fail if either appending some character to the associated output stream fails or if it is unable to establish pbase() and pptr() according to the above rules.
That is, for each class derived from an instance of basic_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 when traits::eq_int_type(c, traits::eof()) returns true, in which case it returns traits::not_eof(c).