# <strstream>

<head><title>&lt;strstream&gt;</title></head>

# `<strstream>`

* * *

Include the [iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string).

    namespace std {
    class strstreambuf;
    class istrstream;
    class ostrstream;
    class strstream;
    }  // namespace stdCopy to clipboard

## `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);
        };Copy to clipboard

The class describes a
**[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer)** 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);Copy to clipboard

If `freezeit` is true, the function alters the stored
[strstreambuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_strstrea.html#strstreambuf%20mode) to make the
controlled sequence frozen. Otherwise, it makes the controlled
sequence not frozen.

### `strstreambuf::pcount`

    streamsize pcount();Copy to clipboard

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);Copy to clipboard

If `meta != EOF`,
the protected virtual member function endeavors to insert the element
`(char)meta`
into the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
It can do so in various ways:

- If a [write position](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#write%20position)
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_strstrea.html#strstreambuf%20mode) 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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).)

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);Copy to clipboard

The protected virtual member function endeavors to put back an element
into the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer),
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#putback%20position)
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_strstrea.html#strstreambuf%20mode)
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);Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
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);Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer).
(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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer).
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();Copy to clipboard

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);Copy to clipboard

The first constructor stores a null pointer in all the pointers
controlling the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer), the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer), and
[strstreambuf allocation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_strstrea.html#strstreambuf%20allocation).
It sets the stored
[strstreambuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_strstrea.html#strstreambuf%20mode) 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);Copy to clipboard

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);Copy to clipboard

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

    setg(getptr, getptr, putptr);
    setp(putptr, getptr + N);Copy to clipboard

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);Copy to clipboard

all behave the same as:

    streambuf((char *)getptr, count);Copy to clipboard

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

### `strstreambuf::underflow`

    virtual int underflow();Copy to clipboard

The protected virtual member function endeavors to extract the current
element `ch` from the
[input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer),
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#read%20position)
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();
        };Copy to clipboard

The class describes an object that controls
extraction of elements and encoded objects from a
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer) 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);Copy to clipboard

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() constCopy to clipboard

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

### `istrstream::str`

    char *str();Copy to clipboard

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;
        };Copy to clipboard

The class describes an object that controls
insertion of elements and encoded objects into a
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer) of class
`strstreambuf`.
The object stores an ojbect of class
`strstreambuf`.

### `ostrstream::freeze`

    void freeze(bool freezeit = true)Copy to clipboard

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

### `ostrstream::ostrstream`

    ostrstream();
    ostrstream(char *ptr, streamsize count,
        ios_base::openmode mode = ios_base::out);Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string)
whose first element is designated
by `ptr`, and the constructor calls
`strstreambuf(ptr, count, ptr +
strlen(ptr)`.

### `ostrstream::pcount`

    streamsize pcount() const;Copy to clipboard

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

### `ostrstream::rdbuf`

    strstreambuf *rdbuf() constCopy to clipboard

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

### `ostrstream::str`

    char *str();Copy to clipboard

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

## `strstream`

    class strstream : public iostream {
    public:
        strstream();
        strstream(char *ptr, streamsize count,
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
        strstreambuf *rdbuf() const;
        void freeze(bool freezeit = true);
        char *str();
        streamsize pcount() const;
        };Copy to clipboard

The class describes an object that controls
insertion and extraction of elements and encoded objects using a
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer) of class
`strstreambuf`.
The object stores an ojbect of class
`strstreambuf`.

### `strstream::freeze`

    void freeze(bool freezeit = true)Copy to clipboard

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

### `strstream::pcount`

    streamsize pcount() const;Copy to clipboard

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

### `strstream::strstream`

    strstream();
    strstream(char *ptr, streamsize count,
        ios_base::openmode mode =
            ios_base::in | ios_base::out);Copy to clipboard

Both constructors initialize the base class by calling
`streambuf(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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string)
whose first element is designated
by `ptr`, and the constructor calls
`strstreambuf(ptr, count, ptr +
strlen(ptr)`.

### `strstream::rdbuf`

    strstreambuf *rdbuf() constCopy to clipboard

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

### `strstream::str`

    char *str();Copy to clipboard

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

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<string></string> Next Topic

<time.h></time.h>