<strstream>
Include the iostreams
standard header <strstream>
to define several classes that support
iostreams operations on
sequences stored in an allocated array of char object.
Such sequences are easily converted to and from
C strings.
namespace std { class strstreambuf; class istrstream; class ostrstream; class strstream; };
strstreambuf
class strstreambuf : public streambuf { public: explicit strstreambuf(streamsize count = 0); strstreambuf(void (*allocfunc)(size_t), void (*freefunc)(void *)); strstreambuf(char *getptr, streamsize count, char *putptr = 0); strstreambuf(signed char *getptr, streamsize count, signed char *putptr = 0); strstreambuf(unsigned char *getptr, streamsize count, unsigned char *putptr = 0); strstreambuf(const char *getptr, streamsize count); strstreambuf(const signed char *getptr, streamsize count); strstreambuf(const unsigned char *getptr, streamsize count); void freeze(bool freezeit = true); char *str(); streamsize pcount(); protected: virtual streampos seekoff(streamoff off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out); virtual streampos seekpos(streampos sp, ios_base::openmode which = ios_base::in | ios_base::out); virtual int underflow(); virtual int pbackfail(int meta = EOF); virtual int overflow(int meta = EOF); };
The class describes a stream buffer that controls the transmission of elements to and from a sequence of elements stored in a char array object. Depending on how it is constructed, the object can be allocated, extended, and freed as necessary to accommodate changes in the sequence.
An object of class strstreambuf
stores several bits of mode information as its
strstreambuf mode.
These bits indicate whether the controlled sequence:
A controlled sequence that is frozen cannot be modified or extended, regardless of the state of these separate mode bits.
The object also stores pointers to two functions that control strstreambuf allocation. If these are null pointers, the object devises its own method of allocating and freeing storage for the controlled sequence.
strstreambuf::freeze
void freeze(bool freezeit = true);
If freezeit
is true, the function alters the stored
strstreambuf mode to make the
controlled sequence frozen. Otherwise, it makes the controlled
sequence not frozen.
strstreambuf::pcount
streamsize pcount();
The member function returns a count of the number of elements
written to the controlled sequence. Specifically, if
pptr()
is a
null pointer, the function returns zero. Otherwise, it returns
pptr() -
pbase()
.
strstreambuf::overflow
virtual int overflow(int meta = EOF);
If meta != EOF
,
the protected virtual member function endeavors to insert the element
(char)meta
into the
output buffer.
It can do so in various ways:
If the function cannot succeed, it returns
EOF
. Otherwise, if meta == EOF
it returns some
value other than EOF
. Otherwise, it returns meta
.
strstreambuf::pbackfail
virtual int pbackfail(int meta = EOF);
The protected virtual member function endeavors to put back an element into the input buffer, then make it the current element (pointed to by the next pointer).
If meta == EOF
,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
ch = (char)meta
.
The function can put back an element in various ways:
ch
,
it can simply decrement the next pointer for the input buffer.ch
into the putback position and decrement the
next pointer for the input buffer.If the function cannot succeed, it returns
EOF
. Otherwise, if meta == EOF
it returns some
value other than EOF
. Otherwise, it returns meta
.
strstreambuf::seekoff
virtual streampos seekoff(streamoff off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf
, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence.
The new position is determined as follows:
way ==
ios_base::beg
,
the new position is the beginning of the stream plus off
.
way ==
ios_base::cur
,
the new position is the current stream position plus off
.
way ==
ios_base::end
,
the new position is the end of the stream plus off
.
If
which & ios_base::in
is nonzero and
the input buffer exist,
the function alters the next position to read in the
input buffer.
If which & ios_base::out
is also nonzero,
way != ios_base::cur
,
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.
Otherwise, if which & ios_base::out
is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions, it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.
strstreambuf::seekpos
virtual streampos seekpos(streampos sp, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf
, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence. The new position is determined
by sp
.
If
which & ios_base::in
is nonzero
and the input buffer exists,
the function alters the next position to read in the
input buffer.
(If which & ios_base::out
is nonzero
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.)
Otherwise, if which & ios_base::out
is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions, it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.
strstreambuf::str
char *str();
The member function calls
freeze()
, then
returns a pointer to the beginning of the controlled sequence.
(Note that no terminating null element exists, unless you insert
one explicitly.)
strstreambuf::strstreambuf
explicit strstreambuf(streamsize count = 0); strstreambuf(void (*allocfunc)(size_t), void (*freefunc)(void *)); strstreambuf(char *getptr, streamsize count, char *putptr = 0); strstreambuf(signed char *getptr, streamsize count, signed char *putptr = 0); strstreambuf(unsigned char *getptr, streamsize count, unsigned char *putptr = 0); strstreambuf(const char *getptr, streamsize count); strstreambuf(const signed char *getptr, streamsize count); strstreambuf(const unsigned char *getptr, streamsize count);
The first constructor stores a null pointer in all the pointers
controlling the
input buffer, the
output buffer, and
strstreambuf allocation.
It sets the stored
strstreambuf mode to make the
controlled sequence modifiable and extendable.
And it accepts count
as a suggested initial allocation size.
The second constructor behaves much as the first, except that
it stores allocfunc
as the pointer to the function to
call to allocate storage, and freefunc
as the pointer
to the function to call to free that storage.
The three constructors:
strstreambuf(char *getptr, streamsize count, char *putptr = 0); strstreambuf(signed char *getptr, streamsize count, signed char *putptr = 0); strstreambuf(unsigned char *getptr, streamsize count, unsigned char *putptr = 0);
also behave much as the first, except that getptr
designates the array object used to hold the controlled
sequence. (Hence, it must not be a null pointer.) The number
of elements N
in the array is determined as
follows:
(count > 0)
, then N
is count
.(count == 0)
, then N
is
strlen((const char *)getptr)
.(count < 0)
, then N
is
INT_MAX
.If putptr
is a null pointer, the function establishes
just an input buffer, by executing:
setg(getptr, getptr, getptr + N);
Otherwise, it establishes both input and output buffers, by executing:
setg(getptr, getptr, putptr); setp(putptr, getptr + N);
In this case, putptr
must be in the interval
[getptr, getptr + N]
.
Finally, the three constructors:
strstreambuf(const char *getptr, streamsize count); strstreambuf(const signed char *getptr, streamsize count); strstreambuf(const unsigned char *getptr, streamsize count);
all behave the same as:
streambuf((char *)getptr, count);
except that the stored mode makes the controlled sequence neither modifiable not extendable.
strstreambuf::underflow
virtual int underflow();
The protected virtual member function endeavors to extract the current
element ch
from the
input buffer,
then advance the current stream position, and return the element as
(int)(unsigned char)ch
.
It can do so in only one way:
If a read position
is available, it takes ch
as the element stored
in the read position and advances the next pointer for the input buffer.
If the function cannot succeed, it returns
EOF
. Otherwise,
it returns the current element in the input stream,
converted as described above.
istrstream
class istrstream : public istream { public: explicit istrstream(const char *ptr); explicit istrstream(char *ptr); istrstream(const char *ptr, streamsize count); istrstream(char *ptr, streamsize count); strstreambuf *rdbuf() const; char *str(); };
The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
strstreambuf
.
The object stores an ojbect of class
strstreambuf
.
istrstream::istrstream
explicit istrstream(const char *ptr); explicit istrstream(char *ptr); istrstream(const char *ptr, streamsize count); istrstream(char *ptr, streamsize count);
All the constructors initialize the base class by calling
istream(sb)
,
where sb
is the stored object of class
strstreambuf
.
The first two constructors also initialize sb
by calling
strstreambuf((const
char *)ptr, 0)
. The remaining two constructors instead call
strstreambuf((const char *)ptr, count)
.
istrstream::rdbuf
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf
.
istrstream::str
char *str();
The member function returns
rdbuf()->
str()
.
ostrstream
class ostrstream : public ostream { public: ostrstream(); ostrstream(char *ptr, streamsize count, ios_base::openmode mode = ios_base::out); strstreambuf *rdbuf() const; void freeze(bool freezeit = true); char *str(); streamsize pcount() const; };
The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
strstreambuf
.
The object stores an ojbect of class
strstreambuf
.
ostrstream::freeze
void freeze(bool freezeit = true)
The member function calls
rdbuf()->
freeze(freezeit)
.
ostrstream::ostrstream
ostrstream(); ostrstream(char *ptr, streamsize count, ios_base::openmode mode = ios_base::out);
Both constructors initialize the base class by calling
ostream(sb)
,
where sb
is the stored object of class
strstreambuf
.
The first constructor also initializes sb
by calling
strstreambuf()
.
The second constructor initializes the base class one of two ways:
mode &
ios_base::app == 0
, then
ptr
must designate the first element of an array of count
elements, and the constructor calls
strstreambuf(ptr, count, ptr)
.ptr
must designate the first element of an
array of count
elements that contains a
C string
whose first element is designated
by ptr
, and the constructor calls
strstreambuf(ptr, count, ptr +
strlen(ptr)
.ostrstream::pcount
streamsize pcount() const;
The member function returns
rdbuf()->
pcount()
.
ostrstream::rdbuf
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf
.
ostrstream::str
char *str();
The member function returns
rdbuf()->
str()
.
strstream
class strstream : public iostream { public: strstream(); strstream(char *ptr, streamsize count, ios_base::openmode mode = ios_base::in | ios_base::out); strstreambuf *rdbuf() const; void freeze(bool freezeit = true); char *str(); streamsize pcount() const; };
The class describes an object that controls
insertion and extraction of elements and encoded objects using a
stream buffer of class
strstreambuf
.
The object stores an ojbect of class
strstreambuf
.
strstream::freeze
void freeze(bool freezeit = true)
The member function calls
rdbuf()->
freeze(freezeit)
.
strstream::pcount
streamsize pcount() const;
The member function returns
rdbuf()->
pcount()
.
strstream::strstream
strstream(); strstream(char *ptr, streamsize count, ios_base::openmode mode = ios_base::in | ios_base::out);
Both constructors initialize the base class by calling
streambuf(sb)
,
where sb
is the stored object of class
strstreambuf
.
The first constructor also initializes sb
by calling
strstreambuf()
.
The second constructor initializes the base class one of two ways:
mode &
ios_base::app == 0
, then
ptr
must designate the first element of an array of count
elements, and the constructor calls
strstreambuf(ptr, count, ptr)
.ptr
must designate the first element of an
array of count
elements that contains a
C string
whose first element is designated
by ptr
, and the constructor calls
strstreambuf(ptr, count, ptr +
strlen(ptr)
.strstream::rdbuf
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf
.
strstream::str
char *str();
The member function returns
rdbuf()->
str()
.
See also the Table of Contents and the Index.
Copyright © 1992-2002 by P.J. Plauger. All rights reserved.