Name

basic_stringbuf class template — Base class for string buffers

Synopsis

template <class charT, class traits = char_traits<charT>,
          class Alloc = allocator<charT> >
class basic_stringbuf : public basic_streambuf<charT,traits>
{
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;
  explicit basic_stringbuf(ios_base::openmode mode = ios_base::in | 
                           ios_base::out);
  explicit basic_stringbuf(const basic_string<charT,traits,Alloc>& str,
                           ios_base::openmode mode = ios_base::in | 
                           ios_base::out);
  basic_string<charT,traits,Alloc> str(  ) const;
  void str(const basic_string<charT,traits,Alloc>& s);
protected:
  virtual int_type underflow(  );
  virtual int_type pbackfail(int_type c = traits::eof(  ));
  virtual int_type overflow (int_type c = traits::eof(  ));
  virtual basic_streambuf<charT,traits>* setbuf(charT*, streamsize);
  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);
};

The basic_stringbuf class template implements a stream buffer for string-based streams. A string buffer maintains a single character buffer with separate positions for reading and writing. That is, the buffer has begin, next, and end pointers for reading and separate begin, next, and end pointers for writing. The begin pointer points to the start of a buffer, and the end pointer points to one past the end of the buffer. The next pointer points to the position where the next character will be read or written. Refer to basic_streambuf in <streambuf> for details about buffer positions.

In the following descriptions of the member functions of basic_stringbuf, mode refers to a private copy of the mode parameter that is passed to the constructors. The implementation is not required to have such a data member, but the descriptions below are clearer with the assumption that it exists.

explicit basic_stringbuf (ios_base::openmode mode = ios_base::in | ios_base::out)

Initializes the buffer with an empty string and remembers the mode.

explicit basic_stringbuf (const basic_string<charT,traits,Alloc>& str, ios_base::openmode mode = ios_base::in | ios_base::out)

Initializes the buffer with a copy of str and remembers the mode. If mode & ios_base::in is nonzero, the input position is initialized to read from the start of the buffer. If mode & ios_base::out is nonzero, the output position is initialized to overwrite the buffer.

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

Attempts to append c to the end of the buffer as follows:

The return value is traits::not_eof(c) for success or traits::eof( ) for failure.

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

Attempts to push c back onto the buffer for reading as follows:

The return value is traits::not_eof(c) for success or traits::eof( ) for failure.

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

Sets the stream position. The input position, output position, or both can be set, depending on (which & (ios_base::in | ios_base::out)). The following are the possible results of this expression:

The new position is determined as an offset off, which is added to the position at the start of the stream, the current position, or at the end of the stream, depending on way (ios_base::beg, ios_base::cur, or ios_base::end). If the desired position is negative or past the end of the buffer, the function fails and returns pos_type(-1). If the function succeeds, it returns the new position.

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

Sets the stream position to sp. The input position is set if which & ios_base::in is nonzero. The output position is set if which & ios_base::out is nonzero. If sp is not a valid position, or if neither the input nor the output position is set, seekpos fails and pos_type(-1) is returned. The return value is sp for success. If sp was not returned from a prior call to a positioning function (that is, seekoff, seekpos, tellg, or tellp), the results are undefined.

See Also virtual basic_streambuf<charT,traits>* setbu f (charT*, streamsize)

Calling setbuf(0, 0) has no effect other than to return this. The result of any other call to setbuf is implementation-defined.

basic_string<charT,traits,Alloc> str ( ) const

Returns the contents of the buffer as a string. If the mode allows output (mode & ios_base::out is nonzero), the buffer contents are taken from the output positions; otherwise, the buffer contents are copied from the input positions.

void str (const basic_string<charT,traits,Alloc>& s)

Deallocates the current buffer if one exists and replaces it with a copy of s. If mode & ios_base::in is nonzero, the input positions are set to read from the start of the buffer. If mode & ios_base::out is nonzero, the output positions are set to overwrite the buffer.

virtual int_type underflow ( )

Returns *gptr( ) if more input is available, that is, if there is a read position. Otherwise, the function returns traits::eof( ).