Updated: February 2010
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.
For a list of all members of this type, see basic_streambuf Members.
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.