<strstream>

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.

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

strstreambuf

class strstreambuf : public streambuf {
public:
    explicit strstreambuf(streamsize count = 0);
    strstreambuf(void (*allocfunc)(size_t),
        void (*freefunc)(void *));
    strstreambuf(char *getptr, streamsize count,
        char *putptr = 0);
    strstreambuf(signed char *getptr, streamsize count,
        signed char *putptr = 0);
    strstreambuf(unsigned char *getptr, streamsize count,
        unsigned char *putptr = 0);
    strstreambuf(const char *getptr, streamsize count);
    strstreambuf(const signed char *getptr, streamsize count);
    strstreambuf(const unsigned char *getptr, streamsize count);

    void freeze(bool freezeit = 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 meta = EOF);
    virtual int overflow(int meta = 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:

• has been allocated, and hence needs to be freed eventually
• is modifiable
• is extendable by reallocating storage
• has been frozen and hence needs to be unfrozen before the object is destroyed, or freed (if allocated) by an agency other than the object

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 freezeit = true);

If freezeit 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 meta = EOF);

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

• If a write position is available, it can store the element into the write position and increment the next pointer for the output buffer.
• If the stored strstreambuf mode says the controlled sequence is modifiable, extendable, and not frozen, the function can make a write position available by allocating new for the output buffer. (Extending the output buffer this way also extends any associated input buffer.)

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

strstreambuf::pbackfail

virtual int pbackfail(int meta = 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 meta == EOF, the element to push back is effectively the one already in the stream before the current element. Otherwise, that element is replaced by ch = (char)meta. The function can put back an element in various ways:

• If a putback position is available, and the element stored there compares equal to ch, it can simply decrement the next pointer for the input buffer.
• If a putback position is available, and if the strstreambuf mode says the controlled sequence is modifiable, the function can store ch into the putback position and decrement the next pointer for the input buffer.

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

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 way == ios_base::beg, the new position is the beginning of the stream plus off.
• If way == ios_base::cur, the new position is the current stream position plus off.
• If way == ios_base::end, the new position is the end of the stream plus off.

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 either or both stream positions, 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 either or both stream positions, 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 count = 0);
strstreambuf(void (*allocfunc)(size_t),
    void (*freefunc)(void *));
strstreambuf(char *getptr, streamsize count,
    char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
    signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
    unsigned char *putptr = 0);
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);

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. And it accepts count as a suggested initial allocation size.

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

The three constructors:

strstreambuf(char *getptr, streamsize count,
    char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
    signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
    unsigned char *putptr = 0);

also behave much as the first, except that getptr 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 (count > 0), then N is count.
• If (count == 0), then N is strlen((const char *)getptr).
• If (count < 0), then N is INT_MAX.

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

setg(getptr, getptr, getptr + N);

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

setg(getptr, getptr, putptr);
setp(putptr, getptr + N);

In this case, putptr must be in the interval [getptr, getptr + N].

Finally, the three constructors:

strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);

all behave the same as:

streambuf((char *)getptr, count);

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 ch from the input buffer, then advance the current stream position, and return the element as (int)(unsigned char)ch. It can do so in only one way: If a read position is available, it takes ch 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 *ptr);
    explicit istrstream(char *ptr);
    istrstream(const char *ptr, streamsize count);
    istrstream(char *ptr, streamsize count);
    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 *ptr);
explicit istrstream(char *ptr);
istrstream(const char *ptr, streamsize count);
istrstream(char *ptr, streamsize count);

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 *)ptr, 0). The remaining two constructors instead call strstreambuf((const char *)ptr, count).

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 *ptr, streamsize count,
        ios_base::openmode mode = ios_base::out);
    strstreambuf *rdbuf() const;
    void freeze(bool freezeit = 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 freezeit = true)

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

ostrstream::ostrstream

ostrstream();
ostrstream(char *ptr, streamsize count,
    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:

• If mode & ios_base::app == 0, then ptr must designate the first element of an array of count elements, and the constructor calls strstreambuf(ptr, count, ptr).
• Otherwise, ptr must designate the first element of an array of count elements that contains a C string whose first element is designated by ptr, and the constructor calls strstreambuf(ptr, count, ptr + strlen(ptr).

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-2006 by P.J. Plauger. All rights reserved.