SSBUF(3CC4)SSBUF(3CC4)NAMEssbuf - 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 sbuf‐
prot(3CC4) and sbufpub(3CC4). The get and put pointers point into the
attached array, and moving the get or put pointer corresponds to incre‐
menting 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 applica‐
tions 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 iden‐
tical functionality. For more information, see the C++ 4.1 Library
Reference Manual, Chapter 5, "Using libC in a Multithreaded Environ‐
ment."
A strstreambuf may be used in one of two modes: dynamic or static. In
dynamic mode, the array is automatically allocated 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 automatically. A dynamic strstreambuf
may be frozen, that is, made non-expandable. A frozen or static
strstreambuf may be converted 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 characters will be inserted,
you should either create the buffer with the strstream(int) con‐
structor or use setbuf() (see below), to avoid repeated alloca‐
tion 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 compatible.
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 ini‐
tial 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 initially 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 buf‐
fer. 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 allocation; 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 deallocation sequences.
SEE ALSOios.intro(3CC4), ios(3CC4), sbufprot(3CC4), sbufpub(3CC4),
strstream(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
18 June 1998 SSBUF(3CC4)
