strstreambuf(3C++)
strstreambuf --
streambuf specialized to arrays
Synopsis
#include <iostream.h>
#include <strstream.h>
class strstreambuf : public streambuf {
public:
strstreambuf() ;
strstreambuf(char*, int, char*);
strstreambuf(int);
strstreambuf(unsigned char*, int, unsigned char*);
strstreambuf(void* (*a)(long), void(*f)(void*));
void freeze(int n=1) ;
char* str();
virtual streambuf* setbuf(char*, int)
};
Description
A strstreambuf
is a streambuf that uses an array of bytes (a string) to hold
the sequence of characters.
Given the convention that a char* should be interpreted as
pointing just before the char it really points at, the mapping
between the abstract get/put pointers (see
streambuf_pub(3C++))
and char* pointers is direct.
Moving the pointers corresponds exactly to incrementing
and decrementing the char* values.
To accommodate the need for arbitrary length strings
strstreambuf
supports a dynamic mode.
When a strstreambuf is in dynamic mode, space for
the character sequence is
allocated as needed.
When the sequence is extended too far, it will be copied
to a new array.
In the following descriptions assume:
-- ssb is a strstreambuf*.
-- n is an int.
-- ptr and pstart are char*s or unsigned char*s.
-- a is a void* (*)(long).
-- f is a void* (*)(void*).
Constructors:
strstreambuf()-
Constructs an empty strstreambuf in dynamic mode.
This means that space will be automatically allocated to accommodate the
characters that are put into the strstreambuf (using operators
new and delete).
Because this may require copying the original characters, it is
recommended that when many characters will be inserted, the program
should use setbuf() (described below) to inform the strstreambuf.
strstreambuf(a, f)-
Constructs an empty strstreambuf in dynamic mode.
a is used as the allocator function in dynamic mode.
The argument passed to a will be a long
denoting the number of bytes to be allocated.
If a is null, operator new will be used.
f is used to free (or delete) areas returned by a.
The argument to f will be a pointer to the array allocated by a.
If f is null, operator delete is used.
strstreambuf(n)-
Constructs an empty strstreambuf in dynamic mode.
The initial allocation of space will be at least n bytes.
strstreambuf(ptr, n, pstart)-
Constructs a strstreambuf to use the bytes starting at
ptr.
The strstreambuf will be in static mode; it will not grow dynamically.
If n is positive, then the n bytes starting at ptr are
used as the strstreambuf.
If n is zero, ptr is assumed to point to the beginning of a
null terminated string and the bytes of that string (not including the
terminating null character) will constitute the strstreambuf.
If n is negative, the strstreambuf is assumed to continue
indefinitely.
The get pointer is initialized to ptr.
The put pointer is initialized to pstart.
If pstart is null, then stores will be treated as errors.
If pstart is non-null, then the initial sequence for fetching
(the get area) consists of the bytes between ptr and pstart.
If pstart is null, then the initial get area consists of the entire
array.
If pstart is outside the range of a valid stream buffer, the result of a
subsequent put or get operation is undefined.
Member functions:
ssb->freeze(n)-
Inhibits (when n is nonzero) or permits (when n is zero)
automatic deletion of the current array.
Deletion normally occurs when more space is needed
or when ssb is being destroyed.
Only space obtained via dynamic allocation is ever freed.
It is an error (and the effect is undefined) to store characters
into a strstreambuf that was in dynamic allocation mode
and is now frozen.
It is possible, however, to thaw (unfreeze) such a strstreambuf and
resume storing characters.
ptr=ssb->str()-
Returns a pointer to the first char of the current array and freezes
ssb.
If ssb was constructed with an explicit array, ptr will point
to that array.
If ssb is in dynamic allocation mode, but nothing has yet been
stored, ptr may be null.
ssb->setbuf(0,n)-
ssb remembers n and the next time it does a dynamic
mode allocation, it makes sure that at least n bytes
are allocated.
References
streambuf_pub(3C++),
strstream(3C++)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004