Base buffer class for streams
streambuf objects are in charge of providing reading and writing functionality to/from certain types of character sequences, such as external files or strings.
streambuf objects are usually associated with one specific character sequence, from which they read and write data through an internal memory buffer. The buffer is an array in memory which is expected to be synchronized when needed with the physical content of the associated character sequence.
This is an abstract base class, therefore no objects can be directly instantiated from it. The standard hierarchy defines two classes derived from this one that can be used to directly instantiate objects: filebuf and stringbuf.
Public member functions
The common functionality for all stream buffers is provided through the following public member functions:
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 characters available to read (public member function) |
| snextc | Increase get pointer and return next character (public member function) |
| sbumpc | Get current character and increase get pointer (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 get pointer (public member function) |
Output functions (put):
| sputc | Store character at current put position and increase put pointer (public member function) |
| sputn | Write a sequence of characters (public member function) |
Protected member functions
The public functions do not perform their operations directly on the
associated character sequence, but mostly rely for their interaction with this
associated sequence on internal arrays known as
controlled sequences. Do not confuse the
asociated sequences (i.e. the physical files or strings) with
controlled sequences (i.e. internal arrays or buffers).
Each streambuf object has a controlled input sequence and a controlled output sequence. A specific object may have access to one, both, or none of these, depending on the type of streambuf-derived object or operating options (like whether the object is open for input operations or for output operations, or both).
These controlled sequences are arrays maintained internally by the streambuf object, but accessible for the member functions by means of specific pointers. Three pointers describe the accessible part of each one of the two controlled sequences:
| | beginning
(beginning pointers) | current position
(get/put pointer) | end
(end pointers) |
|---|
| Controlled input sequence | eback | gptr | egptr |
| Controlled output sequence | pbase | pptr | epptr |
All the pointers defining one of the sequences must point to locations of the same array in memory, but each of the groups may be referring to different arrays, different regions of a unique array, or the same array.
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 | Increase 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) |
Virtual protected member functions
Internally, the
streambuf class is an elaborated abstract base class designed to provide a uniform public interface for all derived classes. Each
streambuf-derived class is in charge of defining members that keep the validity of these pointers 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 (virtual protected member function) |
Buffer management and positioning:
| setbuf | Set buffer (virtual protected member function) |
| seekoff | Set internal position pointer to relative position (virtual protected member function) |
| seekpos | Set internal position pointer to absolute position (virtual protected member function) |
| sync | Synchronize stream buffer (virtual protected member function) |
Input functions (get):
| showmanyc | Get number of characters available in the sequence (virtual protected member function) |
| xsgetn | Get sequence of characters (virtual protected member function) |
| underflow | Get character in the case of underflow (virtual protected member function) |
| uflow | Get character in the case of underflow and advance get pointer (virtual protected member function) |
| pbackfail | Put character back in the case of backup underflow (virtual protected member function) |
Output functions (put):
| xsputn | Write sequence of characters (virtual protected member function) |
| overflow | Write character in the case of overflow (virtual protected member function) |
