STRSTREAM(3C++)

NAME
strstream - stream class for ``I/O'' using character arrays

SYNOPSIS

#include <strstream.h>

class ios {
public:
	enum open_mode  { in, out, ate, app, trunc, nocreate, noreplace };
	// see ios(3C++) for remainder ...
};

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

class  strstreambuf : public streambuf {
	// see strstreambuf(3C++) ...
};

class strstreambase : virtual public ios {
	// implementation detail of the Xstream classes ...
};

class istrstream : public strstreambase, public istream {
public:
	istrstream(char* ptr);
	istrstream(char* ptr, int len);
	strstreambuf* rdbuf();
};

class ostrstream : public strstreambase, public ostream {
public:
	ostrstream(char* ptr, int len, int mode=ios::out);
	ostrstream();
	strstreambuf* rdbuf();
	int	pcount();
	char*	str();
};

class strstream : public strstreambase, public iostream {
public:
	strstream();
	strstream(char* ptr, int len, int mode);
	strstreambuf* rdbuf();
	char*	str();
};

DESCRIPTION

Classes istrstream, ostrstream, and strstream are specialization of classes istream, ostream, and iostream, respectively, for I/O using in-memory character arrays. That is, the associated streambuf is a strstreambuf.

An auxiliary class strstreambase is an implementation detail, primarily to provide a set of common functions. It is not further discussed.

  istrstream members

istrstream(ptr)
    Assumes ptr points to a null-terminated array of characters, which will serve as the input source. The null is not part of the input. Seeks, using seekg(), are allowed within the range of the array.

istrstream(ptr, len)
    Assumes ptr points to an array of characters of length len, which will serve as the input source. Seeks, using seekg(), are allowed within the range of the array.

strstreambuf* ssbp = iss.rdbuf()
    Returns a pointer to the strstreambuf associated with iss. This is the same as base class versions of this function, except that the return type is specifically a strstreambuf*.

  ostrstream members

ostrstream()
    Creates an empty output stream, which uses a dynamic (expandable) array of characters (see ssbuf(3C++). Seeks are permitted within the current bounds of the array. Presumably this stream will be converted later to a char* via str() (see below).

ostrstream(ptr, len, mode)
    Creates an output stream using the static (non-expandable) array of len characters starting at ptr. If the ios::ate or ios::app bits are set in mode (see ios(3C++)), the array is assumed to contain a null-terminated string beginning at ptr. Characters will be stored beginning at the null character, but will never go beyond len characters. If those bits are not set in mode, the array is assumed to contain no data, and characters will be stored beginning at ptr. Seeks are allowed within the range of the array.

strstreambuf* ssbp = oss.rdbuf()
    Returns a pointer to the strstreambuf associated with oss. This is the same as base class versions of this function, except that the return type is specifically a strstreambuf*.

int n = oss.pcount()
    Returns the number of characters stored in the array. This is of use particularly when the array contains binary data or is not otherwise null-terminated.

char* ptr = oss.str()
    Returns a pointer to the start of the underlying array, and freezes (see strstreambuf(3C++)) the stream. If the array was dynamically allocated, it will not now be automatically deleted or null-terminated, and is no longer expandable (see freeze() in strstreambuf). Until str() is called, a dynamically allocated array would be automatically freed when the streambuf was destroyed. Afterward, the user is responsible for the array and when to free it.

  strstream members

strstream()
    Creates an empty bidirectional stream, which uses a dynamic (expandable) array of characters (see ssbuf(3C++). Seeks are permitted within the current bounds of the array.

strstream(ptr, len, mode)
    Creates a bidirectional stream using the static (non-expandable) array of len characters starting at ptr. If the ios::ate or ios::app bits are set in mode (see ios(3C++)), the array is assumed to contain a null-terminated string beginning at ptr. Characters will be stored beginning at the null character, but will never go beyond len characters. If those bits are not set in mode, the array is assumed to contain no data, and characters will be stored beginning at ptr. Seeks are allowed within the range of the array.

strstreambuf* ssbp = ss.rdbuf()
    Returns a pointer to the strstreambuf associated with ss. This is the same as base class versions of this function, except that the return type is specifically a strstreambuf*.

char* ptr = ss.str()
    Returns a pointer to the start of the underlying array, and freezes (see strstreambuf(3C++)) the stream. If the array was dynamically allocated, it will not now be automatically deleted or null-terminated, and is no longer expandable (see freeze() in strstreambuf). Until str() is called, a dynamically allocated array would be automatically freed when the streambuf was destroyed. Afterward, the user is responsible for the array and when to free it.

SEE ALSO

ios.intro(3C++), ios(3C++), istream(3C++), ostream(3C++), sbufpub(3C++), ssbuf(3C++),

C++ 4.1 Library Reference Manual:

Chapter 4, "The Iostream Library."