NAME
ssbuf - buffer class for for character arrays
SYNOPSIS
#include <strstream.h> // includes <iostream.h>
class strstreambuf : public streambuf {
public:
strstreambuf();
strstreambuf(int n);
strstreambuf(void* (*a)(long), void (*f)(void*));
strstreambuf(char* _s, int, char* _strt=0);
~strstreambuf();
void freeze_unlocked(int = 1);
void freeze(int = 1);
char* str_unlocked();
char* str();
virtual int doallocate();
virtual int overflow(int);
virtual int underflow();
virtual streambuf* setbuf(char*, int);
virtual streampos seekoff(streamoff, unsafe_ios::seek_dir, int);
};
DESCRIPTION
The strstreambuf class is a specialization of streambufs
using a char array (string) as the source or destination of
characters. Characters are fetched (input) from the array
and consumed by (written to) the array. The basic streambuf
operations are as described in sbufprot(3CC4) and
sbufpub(3CC4). The get and put pointers point into the
attached array, and moving the get or put pointer
corresponds to incrementing or decrementing a char*.
To make streambuf multi-threaded safe (MT safe), that is,
able to work correctly in a multi-threaded environment,
locks have been used in each public member function. An
alternative set of public member functions without locks has
been introduced for use in single threaded applications
where performance is critical. These member functions share
the same name as the original function with the addition of
the suffix: _unlocked. Other than being MT unsafe, the
member functions have identical functionality. For more
information, see the C++ 4.1 Library Reference Manual,
Chapter 5, "Using libC in a Multithreaded Environment."
A strstreambuf may be used in one of two modes: dynamic or
static. In dynamic mode, the array is automatically allo-
cated and expanded as needed to accomodate strings of any
length. When more space is needed, a new reserve area is
allocated and the data from the old array is copied to it;
the old array is then deleted. In static mode, a user-
supplied fixed array is used, which cannot be moved or
changed to a new buffer; it will never be deleted automati-
cally. A dynamic strstreambuf may be frozen, that is, made
non-expandable. A frozen or static strstreambuf may be con-
verted to a char* for use in expressions which need C-style
strings. A frozen dynamic strstreambuf may be unfrozen:
made expandable again.
Constructors
strstreambuf()
Constructs an empty, dynamic, unfrozen strstreambuf.
Space for the string will be allocated automatically as
needed. If you know that some minimum number of char-
acters will be inserted, you should either create the
buffer with the strstream(int) constructor or use set-
buf() (see below), to avoid repeated allocation and
deallocation of small arrays.
strstreambuf(n)
Constructs an empty, dynamic, unfrozen strstreambuf,
with an initial buffer size of at least n bytes.
strstreambuf(alloc, del)
Constructs an empty, dynamic, unfrozen strstreambuf.
Space for the string will be allocated automatically as
needed. Rather than using new and delete, the supplied
functions alloc and del will be called. Function alloc
must take a long parameter, the number of bytes to
allocate; it must return a pointer to the allocated
space (of type void*), or zero on failure. If alloc is
null, new will be used. Function del must take a
parameter of type void*, which will be a pointer value
acquired from alloc; its return type is void. If del
is null, delete will be used. You must take care when
using this constructor that alloc and del are compati-
ble.
strstreambuf(ptr, len, putp)
Constructs a static strstreambuf using the buffer
pointed to by ptr. If len is positive and putp is
null, len bytes starting at ptr are used. If putp is
not null, len is ignored, and the initial get area will
run from ptr to putp. If len is zero, ptr is assumed
to point to a null-terminated string, and the area up
to but not including the null byte will be used for the
buffer. If len is negative, the buffer is assumed to
be of unlimited length; quite obviously, this is a
potentially dangerous mode. The get pointer will be
initially set to ptr. The put pointer will be ini-
tially set to putp. If putp is null, stores will be
treated as errors. Examples:
strstreambuf greeting("Hello, world!", 0, 0);
Creates a buffer consisting of the supplied text.
The data may not be over-written or expanded.
char *hi = "Hello, world!";
strstreambuf greeting(hi, 0, hi+7);
Creates a buffer consisting of the supplied text.
The data may be over-written from `w' through `!',
but not expanded.
char *hi = "Hello, world!";
strstreambuf greeting(hi, 5, hi);
Creates a buffer consisting of the supplied text.
The "Hello" portion of the data may be read or
overwritten; the remainder of the buffer is
inaccesable.
Member functions
ssbuf.freeze(i)
If i is non-zero, freezes the dynamic buffer; if zero,
it unfreezes the buffer. Freezing prevents automatic
deletion of the buffer, even when the strstreambuf is
destroyed. It also prevents expansion of the buffer
beyond its current size. You would want to freeze a
buffer to permit taking a pointer to it which remains
reliable until the buffer is explicitly unfrozen. Once
unfrozen, a dynamic buffer may be automatically
expanded and deleted. Freezing is irrelevant for a
static buffer, since it is never automatically expanded
or deleted. Freezing does not null-terminate the
buffer.
char* p = ssbuf.str()
Freezes ssbuf and returns a pointer to the beginning of
the buffer. If ssbuf is in dynamic mode but the buffer
is empty, the returned pointer might be null.
streambuf* sbp = ssbuf.setbuf(ptr, len)
If ptr is not null, the request is ignored; it is not
possible to replace the buffer of any static or dynamic
strstreambuf. If ptr is null, the value of len is
saved, and the next dynamic mode allocation will be at
least len bytes. (This applies only to the next allo-
cation; the value of len is then discarded.) You would
want to use this function to force a suitably large
allocation when a buffer was going to be expanded,
avoiding potentially many small allocation and deallo-
cation sequences.
SEE ALSO
ios.intro(3CC4), ios(3CC4), sbufprot(3CC4), sbufpub(3CC4),
strstream(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Environment."
Chapter 4, "Using Classic iostream in a Multithreaded