ssbuf - buffer class for for character arrays
#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);
};
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 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.
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) constructor or use setbuf() (see below), to avoid repeated allocation and deallocation of small arrays.
Constructs an empty, dynamic, unfrozen strstreambuf, with an initial buffer size of at least n bytes.
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.
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 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.
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.
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.
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.
ios (3CC4) , ios.intro (3CC4) , sbufprot (3CC4) , sbufpub (3CC4) , strstream (3CC4)
C++ Library Reference, Chapter 3, "The Classic iostream Library" and Chapter 4, "Using Classic iostreams in a Multithreaded Environment."