class template
<streambuf> <iostream>
std::basic_streambuf
template <class charT, class traits = char_traits<charT> > class basic_streambuf;
Base buffer class for streams
This template is designed as base virtual class for all stream buffer classes.
A stream buffer is an object in charge of performing the reading and writing operations of the stream object it is associated with: the stream delegates all such operations to its associated stream buffer object, which is an intermediary between the stream and its controlled input and output sequences.
All stream objects, no matter whether buffered or unbuffered, have an associated stream buffer: Some stream buffer types may then be set to either use an intermediate buffer or not.
Stream buffer objects keep internally, at least:
- A locale object, used for locale-dependent operations.
- A set of internal pointers to keep an input buffer: eback, gptr, egptr.
- A set of internal pointers to keep an output buffer: pbase, pptr, epptr.
Internally, the basic_streambuf class is an elaborated base class designed to provide a uniform public interface for all derived classes: These public functions call virtual protected members that derived classes may override to implement specific behavior. These overridden virtual functions have access to the internals of the basic_streambuf class by means of a set of protected functions (see below).
Template parameters
- charT
- Character type.
This shall be a non-array POD type.
Aliased as member type basic_streambuf::char_type.
- traits
- Character traits class that defines essential properties of the characters used by stream objects (see char_traits).
traits::char_type shall be the same as charT.
Aliased as member type basic_streambuf::traits_type.
Template instantiations
- streambuf
- Base buffer class for streams (class)
- wstreambuf
- Base buffer class for streams (wide) (class)
These instantiations are declared in <streambuf>, which is included by reference in <iostream>.
Public member functions
The common functionality for all stream buffers is provided through the following public member functions:
- (constructor)
- Construct object (public member function)
- (destructor)
- Destroy object (public member function)
Locales:
- pubimbue
- Imbue locale (public member function)
- getloc
- Get current locale (public member function)
Buffer management and positioning:
- pubsetbuf
- Set buffer array (public member function)
- pubseekoff
- Set internal position pointer to relative position (public member function)
- pubseekpos
- Set internal position pointer to absolute position (public member function)
- pubsync
- Synchronize stream buffer (public member function)
Input functions (get):
- in_avail
- Get number of character available to read (public member function)
- snextc
- Advance to next position and get character (public member function)
- sbumpc
- Get current character and advance to next position (public member function)
- sgetc
- Get current character (public member function)
- sgetn
- Get sequence of characters (public member function)
- sputbackc
- Put character back (public member function)
- sungetc
- Decrease current position (public member function)
Output functions (put):
- sputc
- Put character and advance to next position (public member function)
- sputn
- Put sequence of characters (public member function)
Protected member functions
The public functions do not perform their operations directly on the controlled input and output sequences, but mostly rely on two arrays accessible by a set of internal pointers:
| | beginning
(beginning pointers) | current position
(get/put pointer) | end
(end pointers) |
|---|
| Input sequence | eback | gptr | egptr |
| Output sequence | pbase | pptr | epptr |
The following protected member functions provide access to these pointers:
Input sequence (get):
- eback
- Pointer to beginning of input sequence (protected member function)
- gptr
- Pointer to current position of input sequence (protected member function)
- egptr
- Pointer to end of input sequence (protected member function)
- gbump
- Advance get pointer (protected member function)
- setg
- Set input sequence pointers (protected member function)
Output sequence (put):
- pbase
- Pointer to beginning of output sequence (protected member function)
- pptr
- Pointer to current position of output sequence (protected member function)
- epptr
- Pointer to end of output sequence (protected member function)
- pbump
- Increase put pointer (protected member function)
- setp
- Set output sequence pointers (protected member function)
Copying:
- operator=
- Stream buffer assignment (public member function)
- swap
- Swap stream buffers (public member function)
Virtual protected member functions
Each streambuf-derived class shall define members that keep the validity of the pointers above with respect to their own type of controlled sequence; Modifying the values of the pointers, reallocating the sequences themselves and perfoming all necessary synchronizations with the associated character sequence.
With this design, the core functionality involving the process of reading and writing directly to the specific associated character sequence and to manage the controlled sequences is provided by means of virtual functions, which are overriden as necessary by derived classes:
Locales:
- imbue
- Imbue locale (protected virtual member function)
Buffer management and positioning:
- setbuf
- Set buffer (protected virtual member function)
- seekoff
- Set internal position pointer to relative position (protected virtual member function)
- seekpos
- Set internal position pointer to absolute position (protected virtual member function)
- sync
- Synchronize stream buffer (protected virtual member function)
Input functions (get):
- showmanyc
- Get number of characters available (protected virtual member function)
- xsgetn
- Get sequence of characters (protected virtual member function)
- underflow
- Get character on underflow (protected virtual member function)
- uflow
- Get character on underflow and advance position (protected virtual member function)
- pbackfail
- Put character back on underflow (protected virtual member function)
Output functions (put):
- xsputn
- Put sequence of characters (public member function)
- overflow
- Put character on overflow (protected virtual member function)