<strstream>


// DECLARATIONS
    class strstreambuf;
    class istrstream;
    class ostrstream;
// END OF DECLARATIONS

Include the iostreams standard header <strstream> to define several classes that support iostreams operations on sequences stored in an allocated array of char object. Such sequences are easily converted to and from C strings.

strstreambuf

class strstreambuf : public streambuf {
public:
    explicit strstreambuf(streamsize n = 0);
    strstreambuf(void (*palloc)(size_t),
        void (*pfree)(void *));
    strstreambuf(char *gp, streamsize n,
        char *pp = 0);
    strstreambuf(signed char *gp, streamsize n,
        signed char *pp = 0);
    strstreambuf(unsigned char *gp, streamsize n,
        unsigned char *pp = 0);
    strstreambuf(const char *gp, streamsize n);
    strstreambuf(const signed char *gp, streamsize n);
    strstreambuf(const unsigned char *gp, streamsize n);
    void freeze(bool frz = true);
    char *str();
    streamsize pcount();
protected:
    virtual streampos seekoff(streamoff off,
        ios_base::seekdir way,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    virtual streampos seekpos(streampos sp,
        ios_base::openmode which =
            ios_base::in | ios_base::out);
    virtual int underflow();
    virtual int pbackfail(int c = EOF);
    virtual int overflow(int c = EOF);
    };

The class describes a stream buffer that controls the transmission of elements to and from a sequence of elements stored in a char array object. Depending on how it is constructed, the object can be allocated, extended, and freed as necessary to accommodate changes in the sequence.

An object of class strstreambuf stores several bits of mode information as its strstreambuf mode. These bits indicate whether the controlled sequence:

A controlled sequence that is frozen cannot be modified or extended, regardless of the state of these separate mode bits.

The object also stores pointers to two functions that control strstreambuf allocation. If these are null pointers, the object devises its own method of allocating and freeing storage for the controlled sequence.

strstreambuf::freeze

void freeze(bool frz = true);

If frz is true, the function alters the stored strstreambuf mode to make the controlled sequence frozen. Otherwise, it makes the controlled sequence not frozen.

strstreambuf::pcount

streamsize pcount();

The member function returns a count of the number of elements written to the controlled sequence. Specifically, if pptr() is a null pointer, the function returns zero. Otherwise, it returns pptr() - pbase().

strstreambuf::overflow

virtual int overflow(int c = EOF);

If c != EOF, the protected virtual member function endeavors to insert the element (char)c into the output buffer. It can do so in various ways:

If the function cannot succeed, it returns EOF. Otherwise, if c == EOF it returns some value other than EOF. Otherwise, it returns c.

strstreambuf::pbackfail

virtual int pbackfail(int c = EOF);

The protected virtual member function endeavors to put back an element into the input buffer, then make it the current element (pointed to by the next pointer).

If c == EOF, the element to push back is effectively the one already in the stream before the current element. Otherwise, that element is replaced by x = (char)c. The function can put back an element in various ways:

If the function cannot succeed, it returns EOF. Otherwise, if c == EOF it returns some value other than EOF. Otherwise, it returns c.

strstreambuf::seekoff

virtual streampos seekoff(streamoff off,
    ios_base::seekdir way,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The protected virtual member function endeavors to alter the current positions for the controlled streams. For an object of class strstreambuf, a stream position consists purely of a stream offset. Offset zero designates the first element of the controlled sequence.

The new position is determined as follows:

If which & ios_base::in is nonzero and the input buffer exist, the function alters the next position to read in the input buffer. If which & ios_base::out is also nonzero, way != ios_base::cur, and the output buffer exists, the function also sets the next position to write to match the next position to read.

Otherwise, if which & ios_base::out is nonzero and the output buffer exists, the function alters the next position to write in the output buffer. Otherwise, the positioning operation fails. For a positioning operation to succeed, the resulting stream position must lie within the controlled sequence.

If the function succeeds in altering the stream position(s), it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.

strstreambuf::seekpos

virtual streampos seekpos(streampos sp,
    ios_base::openmode which =
        ios_base::in | ios_base::out);

The protected virtual member function endeavors to alter the current positions for the controlled streams. For an object of class strstreambuf, a stream position consists purely of a stream offset. Offset zero designates the first element of the controlled sequence. The new position is determined by sp.

If which & ios_base::in is nonzero and the input buffer exists, the function alters the next position to read in the input buffer. (If which & ios_base::out is nonzero and the output buffer exists, the function also sets the next position to write to match the next position to read.) Otherwise, if which & ios_base::out is nonzero and the output buffer exists, the function alters the next position to write in the output buffer. Otherwise, the positioning operation fails. For a positioning operation to succeed, the resulting stream position must lie within the controlled sequence.

If the function succeeds in altering the stream position(s), it returns the resultant stream position. Otherwise, it fails and returns an invalid stream position.

strstreambuf::str

char *str();

The member function calls freeze(), then returns a pointer to the beginning of the controlled sequence. (Note that no terminating null element exists, unless you insert one explicitly.)

strstreambuf::strstreambuf

explicit strstreambuf(streamsize n = 0);
strstreambuf(void (*palloc)(size_t),
    void (*pfree)(void *));
strstreambuf(char *gp, streamsize n,
    char *pp = 0);
strstreambuf(signed char *gp, streamsize n,
    signed char *pp = 0);
strstreambuf(unsigned char *gp, streamsize n,
    unsigned char *pp = 0);
strstreambuf(const char *gp, streamsize n);
strstreambuf(const signed char *gp, streamsize n);
strstreambuf(const unsigned char *gp, streamsize n);

The first constructor stores a null pointer in all the pointers controlling the input buffer, the output buffer, and strstreambuf allocation. It sets the stored strstreambuf mode to make the controlled sequence modifiable and extendable.

The second constructor behaves much as the first, except that it stores palloc as the pointer to the function to call to allocate storage, and pfree as the pointer to the function to call to free that storage.

The three constructors:

strstreambuf(char *gp, streamsize n,
    char *pp = 0);
strstreambuf(signed char *gp, streamsize n,
    signed char *pp = 0);
strstreambuf(unsigned char *gp, streamsize n,
    unsigned char *pp = 0);

also behave much as the first, except that gp designates the array object used to hold the controlled sequence. (Hence, it must not be a null pointer.) The number of elements N in the array is determined as follows:

If pp is a null pointer, the function establishes just an input buffer, by executing:

setg(gp, gp, gp + N);

Otherwise, it establishes both input and output buffers, by executing:

setg(gp, gp, pp);
setp(pp, gp + N);

In this case, pp must be in the interval [gp, gp + N].

Finally, the three constructors:

strstreambuf(const char *gp, streamsize n);
strstreambuf(const signed char *gp, streamsize n);
strstreambuf(const unsigned char *gp, streamsize n);

all behave the same as:

streambuf((char *)gp, n);

except that the stored mode makes the controlled sequence neither modifiable not extendable.

strstreambuf::underflow

virtual int underflow();

The protected virtual member function endeavors to extract the current element c from the input buffer, then advance the current stream position, and return the element as (int)(unsigned char)c. It can do so in only one way: If a read position is available, it takes c as the element stored in the read position and advances the next pointer for the input buffer.

If the function cannot succeed, it returns EOF. Otherwise, it returns the current element in the input stream, converted as described above.

istrstream

class istrstream : public istream {
public:
    explicit istrstream(const char *s);
    explicit istrstream(char *s);
    istrstream(const char *s, streamsize n);
    istrstream(char *s, streamsize n);
    strstreambuf *rdbuf() const;
    char *str();
    };

The class describes an object that controls extraction of elements and encoded objects from a stream buffer of class strstreambuf. The object stores an ojbect of class strstreambuf.

istrstream::istrstream

explicit istrstream(const char *s);
explicit istrstream(char *s);
istrstream(const char *s, streamsize n);
istrstream(char *s, streamsize n);

All the constructors initialize the base class by calling istream(sb), where sb is the stored object of class strstreambuf. The first two constructors also initialize sb by calling strstreambuf((const char *)s, 0). The remaining two constructors instead call strstreambuf((const char *)s, n).

istrstream::rdbuf

strstreambuf *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to strstreambuf.

istrstream::str

char *str();

The member function returns rdbuf()-> str().

ostrstream

class ostrstream : public ostream {
public:
    ostrstream();
    ostrstream(char *s, streamsize n,
        ios_base::openmode mode = ios_base::out);
    strstreambuf *rdbuf() const;
    void freeze(bool frz = true);
    char *str();
    streamsize pcount() const;
    };

The class describes an object that controls insertion of elements and encoded objects into a stream buffer of class strstreambuf. The object stores an ojbect of class strstreambuf.

ostrstream::freeze

void freeze(bool frz = true)

The member function calls rdbuf()-> freeze(frz).

ostrstream::ostrstream

ostrstream();
ostrstream(char *s, streamsize n,
    ios_base::openmode mode = ios_base::out);

Both constructors initialize the base class by calling ostream(sb), where sb is the stored object of class strstreambuf. The first constructor also initializes sb by calling strstreambuf(). The second constructor initializes the base class one of two ways:

ostrstream::pcount

streamsize pcount() const;

The member function returns rdbuf()-> pcount().

ostrstream::rdbuf

strstreambuf *rdbuf() const

The member function returns the address of the stored stream buffer, of type pointer to strstreambuf.

ostrstream::str

char *str();

The member function returns rdbuf()-> str().


See also the Table of Contents and the Index.

Copyright © 1992-1996 by P.J. Plauger. All rights reserved.