basic_streambuf Class

Article
07/29/2015

Describes an abstract base class for deriving a stream buffer, which controls the transmission of elements to and from a specific representation of a stream.

template<class Elem, class Tr = char_traits<Elem> >
   class basic_streambuf;

Parameters

Elem
A char_type.
Tr
The character traits_type.

Remarks

The template class describes an abstract base class for deriving a stream buffer, which controls the transmission of elements to and from a specific representation of a stream. An object of class basic_streambuf helps control a stream with elements of type Tr, also known as char_type, whose character traits are determined by the class char_traits, also known as traits_type.

Every stream buffer conceptually controls two independent streams: one for extractions (input) and one for insertions (output). A specific representation may, however, make either or both of these streams inaccessible. It typically maintains some relationship between the two streams. What you insert into the output stream of a basic_stringbuf<Elem, Tr> object, for example, is what you later extract from its input stream. When you position one stream of a basic_filebuf<Elem, Tr> object, you position the other stream in tandem.

The public interface to template class basic_streambuf supplies the operations that are common to all stream buffers, however specialized. The protected interface supplies the operations needed for a specific representation of a stream to do its work. The protected virtual member functions let you tailor the behavior of a derived stream buffer for a specific representation of a stream. Each derived stream buffer in this library describes how it specializes the behavior of its protected virtual member functions. The default behavior for the base class, which is often to do nothing, is described in this topic.

The remaining protected member functions control copying to and from any storage supplied to buffer transmissions to and from streams. An input buffer, for example, is characterized by:

eback, a pointer to the beginning of the buffer.
gptr, a pointer to the next element to read.
egptr, a pointer just past the end of the buffer.

Similarly, an output buffer is characterized by:

pbase, a pointer to the beginning of the buffer.
pptr, a pointer to the next element to write.
epptr, a pointer just past the end of the buffer.

For any buffer, the following protocol is used:

If the next pointer is null, no buffer exists. Otherwise, all three pointers point into the same sequence. They can be safely compared for order.
For an output buffer, if the next pointer compares less than the end pointer, you can store an element at the write position designated by the next pointer.
For an input buffer, if the next pointer compares less than the end pointer, you can read an element at the read position designated by the next pointer.
For an input buffer, if the beginning pointer compares less than the next pointer, you can put back an element at the putback position designated by the decremented next pointer.

Any protected virtual member functions you write for a class derived from basic_streambuf<Elem, Tr> must cooperate in maintaining this protocol.

An object of class basic_streambuf<Elem, Tr> stores the six pointers previously described. It also stores a locale object in an object of type locale for potential use by a derived stream buffer.

Constructors

basic_streambuf

Constructs an object of type basic_streambuf.

Typedefs

char_type	Associates a type name with the Elem template parameter.
int_type	Associates a type name within basic_streambuf scope with the Elem template parameter.
off_type	Associates a type name within basic_streambuf scope with the Elem template parameter.
pos_type	Associates a type name within basic_streambuf scope with the Elem template parameter.
traits_type	Associates a type name with the Tr template parameter.

Member Functions

eback	A protected function that returns a pointer to the beginning of the input buffer.
egptr	A protected function that returns a pointer just past the end of the input buffer.
epptr	A protected function that returns a pointer just past the end of the output buffer.
gbump	A protected function that adds _Count to the next pointer for the input buffer.
getloc	Gets the basic_streambuf object's locale.
gptr	A protected function that returns a pointer to the next element of the input buffer.
imbue	A protected, virtual function called by pubimbue.
in_avail	Returns the number of elements that are ready to be read from the buffer.
overflow	A protected virtual function that can be called when a new character is inserted into a full buffer.
pbackfail	A protected virtual member function that tries to put back an element into the input stream, then make it the current element (pointed to by the next pointer).
pbase	A protected function that returns a pointer to the beginning of the output buffer.
pbump	A protected function that adds count to the next pointer for the output buffer.
pptr	A protected function that returns a pointer to the next element of the output buffer.
pubimbue	Sets the basic_streambuf object's locale.
pubseekoff	Calls seekoff, a protected virtual function that is overridden in a derived class.
pubseekpos	Calls seekpos, a protected virtual function that is overridden in a derived class and resets the current pointer position.
pubsetbuf	Calls setbuf, a protected virtual function that is overridden in a derived class.
pubsync	Calls sync, a protected virtual function that is overridden in a derived class and updates the external stream associated with this buffer.
sbumpc	Reads and returns the current element, moving the stream pointer.
seekoff	The protected virtual member function tries to alter the current positions for the controlled streams.
seekpos	The protected virtual member function tries to alter the current positions for the controlled streams.
setbuf	The protected virtual member function performs an operation particular to each derived stream buffer.
setg	A protected function that stores _Gbeg in the beginning pointer, _Gnext in the next pointer, and _Gend in the end pointer for the input buffer.
setp	A protected function that stores _Pbeg in the beginning pointer and _Pend in the end pointer for the output buffer.
sgetc	Returns current element without changing position in the stream.
sgetn	Returns the number of elements read.
showmanyc	Protected virtual member function that returns a count of the number of characters that can be extracted from the input stream and ensure that the program will not be subject to an indefinite wait.
snextc	Reads the current element and returns the following element.
sputbackc	Puts a char_type in the stream.
sputc	Puts a character into the stream.
sputn	Puts a character string into the stream.
stossc	Move past the current element in the stream.
sungetc	Gets a character from the stream.
swap	Exchanges the values in this object for the values in the provided basic_streambuf object parameter.
sync	A protected virtual function that tries to synchronize the controlled streams with any associated external streams.
uflow	A protected virtual function that extracts the current element from the input stream.
underflow	A protected virtual function that extracts the current element from the input stream.
xsgetn	A protected virtual function that extracts elements from the input stream.
xsputn	A protected virtual function that inserts elements into the output stream.

Operators

operator=

Assigns the values of this object from another basic_streambuf object.

Requirements

Header: <streambuf>

Namespace: std