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:

Buffer management and positioning:
Input functions (get):
Output functions (put):

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 pointers)
current position
(get/put pointer)
(end pointers)
Controlled input sequenceebackgptregptr
Controlled output sequencepbasepptrepptr

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):
Output sequence (put):

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:


Buffer management and positioning:

Input functions (get):

Output functions (put):