Partager via


basic_streambuf 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.

For a list of all members of this type, see basic_streambuf Members.

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

Parameters

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.

Notes

Objects of type basic_streambuf are created with an internal buffer of type char * regardless of the char_type specified by the type parameter Elem. This means that a Unicode string (containing wchar_t characters) will be converted to an ANSI string (containing char characters) before it is written to the internal buffer. To store Unicode strings in the buffer, create a new buffer of type wchar_t and set it using the basic_streambuf::pubsetbuf() method. To see an example that demonstrates this behavior, see basic_filebuf Class.

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.

Requirements

Header: <streambuf>

Namespace: std

See Also

Concepts

basic_streambuf Members

<streambuf> Members

Thread Safety in the Standard C++ Library

iostream Programming

iostreams Conventions