strstreambuf(3C++) strstreambuf(3C++)
NAME
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
Copyright 1994 Novell, Inc. Page 1
strstreambuf(3C++) strstreambuf(3C++)
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
Copyright 1994 Novell, Inc. Page 2
strstreambuf(3C++) strstreambuf(3C++)
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++)
Copyright 1994 Novell, Inc. Page 3