strstreambuf class — I/O buffer for character array streams
class strstreambuf : public basic_streambuf<char> { public: explicit strstreambuf(streamsize alsize_arg = 0); strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*)); strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0); strstreambuf(const char* gnext_arg, streamsize n); strstreambuf(signed char* gnext_arg, streamsize n, signed char* pbeg_arg = 0); strstreambuf(const signed char* gnext_arg, streamsize n); strstreambuf(unsigned char* gnext_arg, streamsize n, unsigned char* pbeg_arg = 0); strstreambuf(const unsigned char* gnext_arg, streamsize n); virtual ~strstreambuf( ); void freeze(bool freezefl = true); char* str( ); int pcount( ); protected: virtual int_type overflow (int_type c = EOF); virtual int_type pbackfail(int_type c = EOF); virtual int_type underflow( ); 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 strstreambuf
class
implements a stream buffer for character array streams. An internal
buffer maintains a single character array 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 is to be read or written. Refer to basic_streambuf
in <streambuf>
for details about buffer
positions.
A strstreambuf
object
maintains a set of flags, an allocated buffer size, and two function
pointers for an allocation and deallocation function. If the
allocation function pointer is null, the new[]
operator is used for allocating the
character array; if the deallocation function pointer is null, the
delete[]
operator is used.
The flags are:
allocated
Indicates that the character array has been allocated, so the destructor should delete it
constant
Indicates that the character array is const
, so it cannot be used for
output
dynamic
Indicates that the character array has been dynamically allocated and can grow as needed to accommodate output
frozen
Indicates that the character array can no longer be modified, extended, or freed
The following are the public member functions of strstreambuf
:
explicit
strstreambuf
(streamsize
alloc_size
=
0)
Saves alloc_size
as
the suggested size of the character array, and sets the
dynamic
flag. The
allocation and deallocation functions are set to null
pointers.
strstreambuf
(void*
(*palloc)(size_t), void
(*pfree)(void*))
Sets the dynamic
flag and saves palloc
and
pfree
as the allocation and
deallocation functions.
strstreambuf
(char*
gnext_arg
, streamsize
n,
char* pbeg_arg
=
0)
, strstreambuf
(signed
char*
gnext_arg
, streamsize
n,
signed
char*
pbeg_arg
=
0)
, strstreambuf
(unsigned
char*
gnext_arg
, streamsize
n,
unsigned
char*
pbeg_arg
=
0)
Clears all flags and sets the allocation and
deallocation functions to null pointers. If pbeg_arg
is null, the output
pointers are null and the input buffer is set to n
bytes starting at gnext_arg
by calling setg(gnext_arg
, gnext_arg
, gnext_arg
+
N
)
. If pbeg_arg
is not null, the input
pointers are set by calling setg(gnext_arg
, gnext_arg
, pbeg_arg)
, and the output pointers
are set by calling setp(pbeg_arg
, pbeg_arg
+
N
). N
is determined as follows:
n > 0
N
is n
.
n == 0
N
is strlen(gnext_arg)
.
n < 0
N
is INT_MAX
.
strstreambuf
(const
char*
gnext_arg
, streamsize
n)
, strstreambuf
(const
signed
char*
gnext_arg
, streamsize
n)
, strstreambuf
(const
unsigned
char*
gnext_arg, streamsize
n)
Initializes the buffer pointers in the same manner as
constructing strstreambuf(const_cast<char*>(gnext_arg)
,
n)
. The only difference is
that the constant
flag is
set.
virtual
~strstreambuf
( )
The destructor frees the character array if the
allocated
flag is set and
the frozen
flag is
clear.
void
freeze
(bool freezefl =
true)
Freezes or thaws the character buffer. If the dynamic
flag is set, the freeze
function sets or clears the frozen
flag to match the freezefl
parameter. If the dynamic
flag is clear, freeze( )
does nothing.
char*
str
( )
Returns the internal character buffer by calling
freeze( )
and returning
gbase( )
.
int
pcount
( )
Returns the number of output bytes in the buffer. If
pptr( )
is null, 0
is returned; otherwise, pptr( )
-
pbase( )
is returned.
The overridden virtual functions are:
virtual int_type
overflow
(int_type c =
EOF)
Attempts to append c
to the end of the character array as follows:
If c
==
EOF
, nothing happens and a
non-end-of-file character is returned to indicate
success.
If c
!=
EOF
, and a write position is
available, c
is
appended to the character array by calling sputc(c)
.
If a write position is not available, the dynamic
flag is set, and the
frozen
flag is clear,
then the character array is extended and c
is appended to the array. The
array is extended by allocating a new, larger character
array; copying the old contents (if any); updating the
read and write pointers. If the array is successfully
extended, the allocated
flag is set.
Otherwise, the array cannot be extended, so the function fails.
The return value is c
for success or EOF
for
failure. If c
is EOF
, a value other than EOF
is returned for success.
virtual
int_type
pbackfail
(int_type
c
=
traits::eof( ))
Attempts to push back c
onto the input array for reading
as follows:
If c
==
EOF
, and a putback position is
available, gptr( )
is
set to gptr( )
-
1.
If c
!=
EOF
, a putback position is
available, and gptr(
)[-1]
is equal to c
, gptr( )
is set to gptr( )
- 1.
If c
!=
EOF
, the constant
flag is clear, and a
putback position is available, gptr( )
is set to gptr( )
- 1, and *gptr( )
is assigned c
.
Otherwise, the character cannot be put back, so the function fails.
The return value is c
for success or EOF
for
failure. If c
is EOF
, a value other than EOF
is returned for success.
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:
os_base::in
Sets the input position
os_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 by adding the offset
off
to a base position
given by way
, which must be
one of the following:
ios_base::beg
The base position is the at start of the
stream—that is, off
is an absolute position.
ios_base::cur
The base position is the current stream position.
ios_base::end
The base position is at the end of the stream.
In all cases, a positive offset is toward the end of the
stream, and a negative offset is toward the start of the
stream. If the desired position is negative or past the end of
the string, 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. The
result of any other call to setbuf
is
implementation-defined.
virtual int_type
underflow
( )
Gets another character from the input range without
moving the input pointer. If the stream has a read position,
the function returns *gptr(
)
. If there is no read position, but there is a
non-null write pointer past the end of the input range—that
is, pptr( )
>
gend(
)
—then the read end pointer (gend( )
) is advanced at least one
position but still less than or equal to pptr( )
. The return value is
EOF
for failure or *gnext( )
for success.