sstreambuf Specialization of streambuf for arrays

This section describes how a string may be used as a stream buffer.

---

#include <iostream.h>
#include <strstream.h>

class strstreambuf : public streambuf

{

public:

	strstreambuf() ; strstreambuf(char*, int, char* pstart=0); strstreambuf(int); strstreambuf(unsigned char*, int, unsigned char* pstart=0); strstreambuf(void* (*a)(long), void(*f)(void*));  ˜strstreambuf();
void char* virtual int virtual int	freeze(int n=1) ; str(); doallocate(); overflow(int);
virtual streampos
	seekoff(streamoff, ios::seek_dir, int);
virtual streambuf*
	setbuf(char* p, int n);
virtual int	underflow();

};

---

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 sbufpub) 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 dynamicmode. When a strstreambuf is in dynamic mode, space for the character sequence is allocated as needed. When the sequence is extended too far, it is copied to a new array.

In the following descriptions assume:

• ssb is a strstreambuf*.
• sb is a streambuf*.
• ptr and pstart are char*s or unsigned char*

Constructors

strstreambuf()

Constructs an empty strstreambuf in dynamic mode. This means that space is 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 are to be inserted,the program should use setbuf() (described below) to inform the strstreambuf.

strstreambuf(void (*a)(long), void* (*f)(void*))

Constructs an empty strstreambuf in dynamic mode. a is used as the allocator function in dynamic mode. The argument passed to a is a long denoting the numberof bytes to be allocated. If a is null, operator new is used. f is used to free (or delete) areas returned by a. The argument to f is a pointer to the array allocated by a. If f is null, operator delete is used.

strstreambuf(int n)

Constructs an empty strstreambuf in dynamic mode. The initial allocation of space is at least n bytes.

strstreambuf(char * ptr, int n, char * pstart)
strstreambuf(unsigned char * ptr, int n, unsigned char * pstart)

Constructs a strstreambuf to use the bytes starting at ptr. The strstreambuf is in static mode; it does not grow dynamically. If n is positive, then the n bytes starting atptr 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) constitutes 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 are 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.

Member functions

ssb->freeze(int n)

Inhibits (when n is non-zero) 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.

char* 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 points to that array. If ssb is in dynamic allocation mode, but nothing has yet been stored, ptr may be null.

streambuf * sb=ssb->setbuf(char *, int n)

ssb remembers n and the next time it does a dynamic mode allocation, it makes sure that at least n bytes are allocated.

EXAMPLE

The following program declares a variable of type strstreambuf and initializes it with string p. The str() member function is called to ensure that the text string p is successfully processed by the strstreambuf constructor.

#include <strstream.h>
#include <iostream.h>
#include <string.h>
char * const p = "A very long string indeed \
                  abcdefghijlkmnopqrstuvwxyz\n";
int main()
{
  strstreambuf s(p, 0, (char *) NULL);
  /* The string p is the strstreambuf.     */
  /* The get pointer is to the start of p. */
  char *tp = s.str();
  cout << "length of original string " << strlen(p) << endl;
  cout << "length of strstreambuf string " << strlen(tp) << endl;
  return 0;
}

The result of executing the program is:

length of original string 77
length of strstreambuf string 77
%  CCM0998 CPU time used: 0.0018 seconds

Note how the original string length has not changed..

SEE ALSO

sbufpub, strstream