basic_stringbuf class template — Base class for string buffers
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:
If c
is an
end-of-file character (c
is traits::eof( )
), nothing
happens, and a non-end-of-file character is returned to
indicate success.
If c
is not
end-of-file, and a write position is available, c
is appended to the buffer by
calling sputc(c)
.
If a write position is not available, and the
mode
allows writing
(mode
&
ios_base::out
is nonzero), the
buffer is extended by one character and c
is appended. If the mode
allows reading (mode
&
ios_base::in
is nonzero), the
read end pointer egptr(
)
is set to point to one position past the end
of the buffer.
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:
If c
is an
end-of-file character (c
is traits::eof( )
), and a putback
position is available, gptr(
)
is set to gptr(
)
- 1.
If c
is not an
end-of-file character, and a putback position is
available, and gptr(
)[-1]
is equal to c
, gptr( )
is set to gptr( )
- 1.
If c
is not an
end-of-file character, and a putback position is
available, and the mode
allows writing (mode
&
ios_base::out
is nonzero),
gptr( )
is set to
gptr( )
- 1, and
*gptr( )
is assigned
c
.
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:
ios_base::in
Sets the input position
ios_base::out
Sets the output position
ios_base::in
|
ios_base::out
, and way
is either ios_base::beg
or ios_base::end
Sets input and output positions
The function fails and returns pos_type(-1)
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.
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( )
.
stringbuf class, wstringbuf class, basic_filebuf
in <fstream>
, basic_streambuf
in <streambuf>