Cppin a Nutshell-13.45 <streambuf>

13.45 <streambuf>

The <streambuf> header declares the basic_streambuf class template and its two specializations: streambuf and wstreambuf. A stream buffer object manages low-level access to a sequence of characters. The characters might be stored in an external file or reside entirely in memory. See the <fstream>, <sstream>, and <strstream> headers for examples of different kinds of stream buffers that are derived from basic_streambuf.

Most programs do not use stream buffers directly, but use stream classes instead because they provide a higher-level interface. Each stream object has an associated stream buffer object.

See Chapter 10 for general information on input and output using the stream classes.

basic_streambuf class template

Stream buffer

template <class charT, class traits = char_traits<charT> >
class basic_streambuf{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;
  virtual ~basic_streambuf(  );
   
  locale pubimbue(const locale &loc);
  locale getloc(  ) const;
  basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n);
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
                      ios_base::openmode which = ios_base::in | ios_base::out);
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
                      ios_base::open_mode which=ios_base::in | ios_base::out);
  pos_type pubseekpos(pos_type sp, ios_base::openmode which = ios_base::in | 
                      ios_base::out);
  pos_type pubseekpos(pos_type sp,ios_base::open_mode which);
  int pubsync(  );
  // Input
  streamsize in_avail(  );
  int_type snextc(  );
  int_type sbumpc(  );
  int_type stossc(  );
  int_type sgetc(  );
  streamsize sgetn(char_type* s, streamsize n);
  // Putback
  int_type sputbackc(char_type c);
  int_type sungetc(  );
  // Output
  int_type sputc(char_type c);
  streamsize sputn(const char_type* s, streamsize n);
protected:
  basic_streambuf(  );
  // Input
  char_type* eback(  ) const;
  char_type* gptr(  ) const;
  char_type* egptr(  ) const;
  void gbump(int n);
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
  // Output
  char_type* pbase(  ) const;
  char_type* pptr(  ) const;
  char_type* epptr(  ) const;
  void pbump(int n);
  void setp(char_type* pbeg, char_type* pend);
  // Locales
  virtual void imbue(const locale &loc);
  // Buffer management and positioning
  virtual basic_streambuf<char_type,traits>* 
    setbuf(char_type* s, streamsize n);
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
                           ios_base::openmode which = ios_base::in | 
                           ios_base::out);
  virtual pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in |
                           ios_base::out);
  virtual streamsize showmanyc(  );
  virtual int sync(  );
  virtual int_type underflow(  );
  virtual int_type uflow(  );
  virtual streamsize xsgetn(char_type* s, streamsize n);
  // Putback
  virtual int_type pbackfail(int_type c = traits::eof(  ));
  // Output
  virtual int_type overflow(int_type c = traits::eof(  ));
  virtual streamsize xsputn(const char_type* s, streamsize n);
};

The basic_streambuf class template manages an input buffer and an output buffer, in which each buffer is an array of characters. The base character type is a template parameter, charT. A buffer has the following three pointers to the array (the names below are not part of the standard but are used for informational purposes only):

begin: Points to the beginning of the array
next: Points to the next element in the array, that is, the next character to read or the position at which to write the next character
end: Points to one past the end of the array

The pointers in this list can all be null pointers, which makes the stream "buffer" unbuffered. If the pointers are not null, the following rules apply:

If next < end for an output array, the stream buffer is said to have a write position. The next output character is written to *next.
If begin < next for an input array, the stream buffer is said to have a push back position. When a character is pushed back, it is stored in next[-1].
If next < end for an input array, the stream buffer is said to have a read position. The next character to read from the buffer is *next.

Figure 13-25 depicts an input buffer, in which the characters "Hello, world." have been fetched from the input source. So far, the first six characters have been read from the input buffer, and the next character to read is the space between "Hello," and "world."

Figure 13-25. Input stream buffer

Figure 13-26 depicts an output buffer, which has room for 12 characters. So far, the buffer contains the five characters "Hello".

Figure 13-26. Output stream buffer

Several functions come in pairs: a public function that is the public interface and a protected, virtual function to do the actual work. For example, pubsync is a public function that simply calls sync, which is protected and virtual. The name of the public function is pub followed by the name of the protected function. The two exceptions are sgetn and sputn, which are public, with xsgetn and xsputn as their protected counterparts.

The basic_streambuf class template implements minimal functionality for managing the buffer pointers. Derived-class templates must override the virtual functions to provide concrete behavior. See basic_filebuf in <fstream>, basic_stringbuf in <sstream>, and strstreambuf in <strstream> for examples of derived classes and templates.

The following descriptions start with the expected public behavior. If you are writing a stream class that uses a stream buffer, you can rely on that behavior from the stream buffer object. If you are writing your own derived-class template, that is the behavior you must implement. Each description ends with the actual implementation in basic_streambuf.

When comparing characters, converting characters to integers or integers to characters, and obtaining the end-of-file marker, basic_streambuf uses the character traits specified by the traits template parameter. See <string> for information about the default character traits, char_traits.

The following are the public member functions of basic_streambuf:

locale getloc( ) const: Returns the current locale, which can be set by calling pubimbue.
streamsize in_avail( ): Returns the number of characters available for input. The return value is egptr( ) - gptr( ) if the stream buffer has a read position, or the result of calling showmanyc( ) if the stream buffer does not have a read position.
locale pubimbue(const locale &loc): Saves a copy of the locale, loc. Subsequent calls to getloc return a copy of the imbued locale. The basic_streambuf class does not use the locale, but a derived class can use the locale to interpret multibyte characters and for other purposes. When a stream buffer is created, it is initially imbued with the global locale.
pos_type pubseekoff(off_type off, ios_base::seekdir way, ios_base::openmode which=ios_base::in|ios_base::out)
pos_type pubseekoff(off_type off, ios_base::seekdir way, ios_base::open_mode which=ios_base::in|ios_base::out): Returns seekoff(off, way, which), which changes the stream position. The second form is deprecated. See ios_base::openmode in <ios> for details.
pos_type pubseekpos(pos_type sp, ios_base::openmode which=ios_base::in|ios_base::out)
pos_type pubseekpos(pos_type sp, ios_base::open_mode which): Returns seekpos(off, way, which), which changes the stream position. The second form is deprecated. See ios_base::openmode in <ios> for details.
basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n): Returns setbuf(s, n), which typically sets the begin, next, and end array pointers.
int pubsync( ): Returns sync( ), which synchronizes the internal arrays with the external I/O source, if any. The pubsync function returns -1 for a failure and any other value for success.
int_type snextc( ): Returns the next input character and advances the input pointers. Specifically, snextc calls sbumpc( ), and if sbumpc returns traits::eof( ), snextc returns traits::eof( ); otherwise, it returns sgetc( ).
int_type sbumpc( )
int_type stossc( ): Returns the next input character (if one is available) and increments the input array's next pointer. If there is no read position, sbumpc returns uflow( ); otherwise, it returns *gptr( ).

The stossc function is deprecated. If it is implemented, it calls sbumpc( ).

int_type sgetc( ): Returns the next available input character without advancing the input pointer. If no read position is available, sgetc returns underflow( ); otherwise, it returns *gptr( ).
streamsize sgetn(char_type* s, streamsize n): Returns xsgetn(s, n).
virtual streamsize showmanyc( ): Returns an estimate of the number of characters immediately available for input. If showmanyc returns a positive value, at least that many characters can be read before underflow returns traits::eof( ). If showmanyc returns -1, calls to underflow or uflow will fail. If the return value is 0, input might be available, but there is no guarantee. Read the function name as s-how-many-c.
int_type sputbackc(char_type c): Tries to push back the character c so the next read will return c. If a push-back position is available (gptr( ) > ebase( )), and the most recently read character (gptr( )[-1]) is c, the input next pointer is decremented, and *gptr( ) is returned. Otherwise, pbackfail(c) is returned.
int_type sputc(char_type c): Writes the character c to the output array and returns c if an output position is available. Otherwise, sputc returns overflow(c).
streamsize sputn(const char_type* s, streamsize n);: Calls xsputn(s, n) to write a string s of length n.
int_type sungetc( ): Pushes back the character that was read most recently from the input stream. If a push-back position is available, the function decrements the input next pointer and returns *gptr( ); otherwise, it returns pbackfail( ).

The following are the protected member functions of basic_streambuf. Those marked as virtual should probably be overridden in a derived class template.

basic_streambuf( )

Initializes all pointers to null pointers. The locale (as returned from getloc( )) is initialized to the current global locale.

char_type* eback( ) const

Returns the begin pointer for the input array.

char_type* egptr( ) const

Returns the end pointer for the input array.

char_type* epptr( ) const

Returns the end pointer for the output array.

void gbump(int n)

Advances the next pointer for the input array by n characters.

char_type* gptr( ) const

Returns the next pointer for the input array.

virtual void imbue(const locale &loc)

A derived class overrides the imbue function to take whatever action is needed when the stream buffer's locale is changed. For example, the stream buffer might cache facets or other information from the new locale.

The pubimbue function calls imbue before storing a new locale; thus, within the call to imbue, the getloc function returns the old locale, and the loc parameter is the new locale.

The default behavior for imbue is to do nothing.

virtual int_type overflow (int_type c = traits::eof( ))

The stream buffer calls overflow to flush the output buffer when it is full. The overflow function handles the sequence of characters stored in the buffer array, or an empty string if the begin and other pointers are null. If c is not traits::eof( ), c is appended to the output sequence. For example, a file stream buffer might write the array to the file. If an output error occurs, an exception is thrown or traits::eof( ) is returned. For success, any value other than traits::eof( ) is returned.

The default behavior is to do nothing and return traits::eof( ).

virtual int_type pbackfail(int_type c = traits::eof( ))

Handles a push-back failure. When the sungetc or sputbackc functions try to push back a character, they first attempt to adjust the current input next pointer. This can fail for one of three reasons:

Input is unbuffered (gptr( ) == 0).
The input buffer is empty (gptr( ) == eback( )).
The push-back character, c, is not the same character that was most recently read (that is, c != gptr( )[-1]).

If the push-back attempt fails, pbackfail mediates with the external input source, if any, to try to complete the push-back operation. For example, a file stream buffer might adjust the external file position so the next character read from the input array will retrieve the pushed-back character.

If c is traits::eof( ), the input sequence is moved back one position to reread the character at that position. If c is not traits::eof( ), pbackfail tries to ensure that the next character read will be c; the derived class is free to modify the input source, change the stream position, or take another action to push back c.

The return value is traits::eof( ) for failure or any other value for success.

The default behavior is to do nothing and return traits::eof( ).

char_type* pbase( ) const

Returns the output buffer's begin pointer.

void pbump(int n)

Increments the output buffer's next pointer by n characters.

char_type* pptr( ) const

Returns the output buffer's next pointer.

Virtual pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which=ios_base::in|ios_base::out)

Changes the stream position. The default behavior is to do nothing except return pos_type(-1).

virtual pos_type seekpos(pos_type sp, ios_base::openmode which=ios_base::in|ios_base::out)

Changes the stream position. The default behavior is to do nothing except return pos_type(-1).

virtual basic_streambuf<char_type,traits>* setbuf(char_type* s, streamsize n)

Typically sets the internal array pointers. The default behavior is to do nothing and return this.

void setg(char_type* gbegin, char_type* gnext, char_type* gend)

Sets the input array pointers: begin = gbegin, next = gnext, and end = gend.

void setp(char_type* pbegin, char_type* pend)

Sets the output array pointers: begin = next = pbegin and end = pend.

virtual int sync( )

Synchronizes the stream buffer with its external source, if any. Any characters in the output array are written, and all pointers are adjusted as needed. The return value is -1 for failure and anything else for success.

The default behavior is to do nothing and return 0.

virtual int_type uflow( )

Fills the input array and fetches the first character from the array. It is called from sbumpc if the input is not buffered (gptr( ) == 0) or if the input buffer is empty (gptr( ) >= egptr( )). Input is obtained from the external source, and the input pointers are reset.

The key difference between uflow and underflow is that uflow advances the input next pointer after returning the first character in the buffer, but underflow does not.

The return value from uflow is *gptr( ) if there is a read position or traits::eof( ) if there is no more input or some other failure occurs.

The default behavior is to do nothing and return traits::eof( ).

virtual int_type underflow( )

Fills the input array and returns the first character in the array. The sgetc( ) function calls underflow when the input is not buffered (gptr( ) == 0) or when the input buffer is empty (gptr( ) >= egptr( )). Input is obtained from the external source, and the input pointers are reset.

The key difference between uflow and underflow is that uflow advances the input next pointer after returning the first character in the buffer, but underflow does not.

The return value is *gptr( ) if there is a read position or traits::eof( ) if there is no more input or some other failure occurs.

The default behavior is to do nothing and return traits::eof( ).

virtual streamsize xsgetn(char_type* s, streamsize n)

Reads up to n characters from the input stream into the character array that s points to. No null character is appended to s. It is equivalent to calling sbumpc up to n times or until it returns traits::eof( ). The number of characters actually read and stored in s is returned. Derived classes can override this function to provide a more efficient implementation.

virtual streamsize xsputn(const char_type* s, streamsize n)

Writes up to n characters from s to the output stream. It is equivalent to calling sputc up to n times or until it returns traits::eof( ). The number of characters actually written is returned. Derived classes can override this function to provide a more efficient implementation.

13.45 <streambuf>

Figure 13-25. Input stream buffer

Figure 13-26. Output stream buffer

See Also

See Also

See Also