# <sstream>

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

# `<sstream>`

* * *

Include the [iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams)
standard header **`<sstream>`**
to define several template classes that support
iostreams operations on
sequences stored in an allocated array object.
Such sequences are easily converted to and from objects of
template class
`basic_string`.

    namespace std {
    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_stringbuf;
    typedef basic_stringbuf<char> stringbuf;
    typedef basic_stringbuf<wchar_t> wstringbuf;
    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_istringstream;
    typedef basic_istringstream<char> istringstream;
    typedef basic_istringstream<wchar_t> wistringstream;
    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_ostringstream;
    typedef basic_ostringstream<char> ostringstream;
    typedef basic_ostringstream<wchar_t> wostringstream;
    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_stringstream;
    typedef basic_stringstream<char> stringstream;
    typedef basic_stringstream<wchar_t> wstringstream;
    }  // namespace stdCopy to clipboard

## `basic_stringbuf`

    template <class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_stringbuf
            : public basic_streambuf<Elem, Tr> {
    public:
        typedef typename basic_streambuf<Elem, Tr>::char_type
            char_type;
        typedef typename basic_streambuf<Elem, Tr>::traits_type
            traits_type;
        typedef typename basic_streambuf<Elem, Tr>::int_type
            int_type;
        typedef typename basic_streambuf<Elem, Tr>::pos_type
            pos_type;
        typedef typename basic_streambuf<Elem, Tr>::off_type
            off_type;
        typedef Alloc allocator_type;
    
        basic_stringbuf(ios_base::openmode mode =
            ios_base::in | ios_base::out);
        basic_stringbuf(const basic_string<Elem, Tr, Alloc>& str,
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
    
        basic_string<Elem, Tr, Alloc> str() const;
        void str(const basic_string<Elem, Tr, Alloc>& newstr);
    
    protected:
        virtual pos_type seekoff(off_type off,
            ios_base::seekdir way,
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
        virtual pos_type seekpos(pos_type sp,
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
        virtual int_type underflow();
        virtual int_type pbackfail(int_type meta =
            traits_type::eof());
        virtual int_type overflow(int_type meta =
            traits_type::eof());
        };Copy to clipboard

The template 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
of type `Elem`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined by the
class `Tr`,
to and from a sequence of elements
stored in an array object. The object is allocated, extended, and
freed as necessary to accommodate changes in the sequence.

An object of class
`basic_stringbuf<Elem, Tr, Alloc>`
stores a copy of the
`ios_base::openmode`
argument from its constructor as its
**stringbuf mode** `mode`:

- If `mode &
ios_base::in` is nonzero,
the [input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer)
is accessible.
- If `mode &
ios_base::out` is nonzero,
the [output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer)
is accessible.

### `basic_stringbuf::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `basic_stringbuf::basic_stringbuf`

    basic_stringbuf(ios_base::openmode mode =
        ios_base::in | ios_base::out);
    basic_stringbuf(const basic_string<Elem, Tr, Alloc>& str,
        ios_base::openmode mode =
            ios_base::in | ios_base::out);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) and the
[output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer). It
also stores `mode` as the
[stringbuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#stringbuf%20mode).

The second constructor allocates a copy of the sequence controlled
by the string object `str`.
If `mode & ios_base::in` is nonzero,
it sets the input buffer to begin reading
at the start of the sequence.
If `mode & ios_base::out` is nonzero,
it sets the output buffer to begin
writing at the start of the sequence.
It also stores `mode` as the
[stringbuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#stringbuf%20mode).

### `basic_stringbuf::char_type`

    typedef Elem char_type;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `basic_stringbuf::int_type`

    typedef typename traits_type::int_type int_type;Copy to clipboard

The type is a synonym for
`traits_type::int_type`.

### `basic_stringbuf::off_type`

    typedef typename traits_type::off_type off_type;Copy to clipboard

The type is a synonym for
`traits_type::off_type`.

### `basic_stringbuf::overflow`

    virtual int_type overflow(int_type meta =
        traits_type::eof());Copy to clipboard

If `meta` does not compare equal to
`traits_type::eof()`,
the protected virtual member function endeavors to insert the element
`traits_type::to_char_type(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.
- It can make a write position available by allocating
new or additional storage 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 `traits_type::eof()`.
Otherwise, it returns
`traits_type::not_eof(meta)`.

### `basic_stringbuf::pbackfail`

    virtual int_type pbackfail(int_type meta =
        traits_type::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` compares equal to
`traits_type::eof()`,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
`byte =
traits_type::to_char_type(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 `byte`,
it can simply decrement the next pointer for the input buffer.
- If a putback position is available,
and if the [stringbuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#stringbuf%20mode) permits
the sequence to be altered (`mode &
ios_base::out` is nonzero),
it can store `byte` into the putback position and decrement the
next pointer for the input buffer.

If the function cannot succeed, it returns
`traits_type::eof()`. Otherwise, it returns
`traits_type::not_eof(meta)`.

### `basic_stringbuf::pos_type`

    typedef typename traits_type::pos_type pos_type;Copy to clipboard

The type is a synonym for
`traits_type::pos_type`.

### `basic_stringbuf::seekoff`

    virtual pos_type seekoff(off_type off,
        ios_base::seekdir way,
        ios_base::openmode mode =
            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
`basic_stringbuf<Elem, Tr, Alloc>`,
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
`mode & ios_base::in` is nonzero,
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 `mode & ios_base::out` is nonzero,
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).
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function affects both stream positions, `way`
must be `ios_base::beg` or `ios_base::end`
and both streams are positioned at the same element.
Otherwise (or if neither position is affected) the positioning
operation fails.

If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.

### `basic_stringbuf::seekpos`

    virtual pos_type seekpos(pos_type sp,
        ios_base::openmode mode =
            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
`basic_stringbuf<Elem, Tr, Alloc>`,
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
`mode & ios_base::in` is nonzero,
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 `mode & ios_base::out` is nonzero,
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).
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
Otherwise (or if neither position is affected) the positioning
operation fails.

If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.

### `basic_stringbuf::str`

    basic_string<Elem, Tr, Alloc> str() const;
    void str(const basic_string<Elem, Tr, Alloc>& newstr);Copy to clipboard

The first member function returns an object of class
`basic_string<Elem, Tr, Alloc>`,
whose controlled sequence is a copy of the sequence controlled
by `*this`. The sequence copied depends on the stored
[stringbuf mode](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#stringbuf%20mode) `mode`:

- If `mode &
ios_base::out` is nonzero
and an [output buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#output%20buffer) exists,
the sequence is the entire output buffer
(`epptr() -
pbase()`
elements beginning with `pbase()`).
- Otherwise, if `mode &
ios_base::in` is nonzero
and an [input buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#input%20buffer) exists,
the sequence is the entire input buffer
(`egptr() -
eback()`
elements beginning with `eback()`).
- Otherwise, the copied sequence is empty.

The second member function deallocates any sequence currently
controlled by `*this`. It then
allocates a copy of the sequence controlled
by `newstr`. If `mode & ios_base::in` is nonzero,
it sets the input buffer to begin reading
at the beginning of the sequence.
If `mode & ios_base::out` is nonzero,
it sets the output buffer to begin
writing at the beginning of the sequence.

### `basic_stringbuf::traits_type`

    typedef Tr traits_type;Copy to clipboard

The type is a synonym for the template parameter `Tr`.

### `basic_stringbuf::underflow`

    virtual int_type underflow();Copy to clipboard

The protected virtual member function endeavors to extract the current
element `byte` 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
`traits_type::to_int_type(byte)`.
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 `byte` as the element stored
in the read position and advances the next pointer for the input buffer.

If the function cannot succeed, it returns
`traits_type::eof()`. Otherwise,
it returns the current element in the input stream,
converted as described above.

## `basic_istringstream`

    template <class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_istringstream
            : public basic_istream<Elem, Tr> {
    public:
        typedef Alloc allocator_type;
        explicit basic_istringstream(
            ios_base::openmode mode = ios_base::in);
        explicit basic_istringstream(
            const basic_string<Elem, Tr, Alloc>& str,
            ios_base::openmode mode = ios_base::in);
        basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
        basic_string<Elem, Tr, Alloc> str();
        void str(const basic_string<Elem, Tr, Alloc>& newstr);
        };Copy to clipboard

The template 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
`basic_stringbuf<Elem, Tr, Alloc>`,
with elements of type `Elem`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined
by the class `Tr`, and whose elements are allocated by
an allocator of class `Alloc`. The object stores an object of class
`basic_stringbuf<Elem, Tr, Alloc>`.

### `basic_istringstream::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `basic_istringstream::basic_istringstream`

    explicit basic_istringstream(
        ios_base::openmode mode = ios_base::in);
    explicit basic_istringstream(
        const basic_string<Elem, Tr, Alloc>& str,
        ios_base::openmode mode = ios_base::in);Copy to clipboard

The first constructor initializes the base class by calling
`basic_istream(sb)`,
where `sb` is the stored object of class
`basic_stringbuf<Elem, Tr, Alloc>`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(mode | ios_base::in)`.

The second constructor initializes the base class by calling
`basic_istream(sb)`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(str, mode | ios_base::in)`.

### `basic_istringstream::rdbuf`

    basic_stringbuf<Elem, Tr, Alloc> *rdbuf() constCopy to clipboard

The member function returns the address of the stored
stream buffer, of type pointer to
`basic_stringbuf<Elem,
Tr, Alloc>`.

### `basic_istringstream::str`

    basic_string<Elem, Tr, Alloc> str() const;
    void str(const basic_string<Elem, Tr, Alloc>& newstr);Copy to clipboard

The first member function returns
`rdbuf()->
str()`.
The second member function calls `rdbuf()-> str(newstr)`.

## `basic_ostringstream`

    template <class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_ostringstream
            : public basic_ostream<Elem, Tr> {
    public:
        typedef Alloc allocator_type;
        explicit basic_ostringstream(
            ios_base::openmode mode = ios_base::out);
        explicit basic_ostringstream(
            const basic_string<Elem, Tr, Alloc>& str,
            ios_base::openmode mode = ios_base::out);
        basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
        basic_string<Elem, Tr, Alloc> str();
        void str(const basic_string<Elem, Tr, Alloc>& newstr);
        };Copy to clipboard

The template 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
`basic_stringbuf<Elem, Tr, Alloc>`,
with elements of type `Elem`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined
by the class `Tr`, and whose elements are allocated by
an allocator of class `Alloc`. The object stores an object of class
`basic_stringbuf<Elem, Tr, Alloc>`.

### `basic_ostringstream::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `basic_ostringstream::basic_ostringstream`

    explicit basic_ostringstream(
        ios_base::openmode mode = ios_base::out);
    explicit basic_ostringstream(
        const basic_string<Elem, Tr, Alloc>& str,
        ios_base::openmode mode = ios_base::out);Copy to clipboard

The first constructor initializes the base class by calling
`basic_ostream(sb)`,
where `sb` is the stored object of class
`basic_stringbuf<Elem, Tr, Alloc>`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(mode | ios_base::out)`.

The second constructor initializes the base class by calling
`basic_ostream(sb)`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(str, mode | ios_base::out)`.

### `basic_ostringstream::rdbuf`

    basic_stringbuf<Elem, Tr, Alloc> *rdbuf() constCopy to clipboard

The member function returns the address of the stored
stream buffer, of type pointer to
`basic_stringbuf<Elem,
Tr, Alloc>`.

### `basic_ostringstream::str`

    basic_string<Elem, Tr, Alloc> str() const;
    void str(const basic_string<Elem, Tr, Alloc>& newstr);Copy to clipboard

The first member function returns
`rdbuf()->
str()`.
The second member function calls `rdbuf()-> str(newstr)`.

## `basic_stringstream`

    template <class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_stringstream
            : public basic_iostream<Elem, Tr> {
    public:
        typedef Alloc allocator_type;
        explicit basic_stringstream(
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
        explicit basic_stringstream(
            const basic_string<Elem, Tr, Alloc>& str,
            ios_base::openmode mode =
                ios_base::in | ios_base::out);
        basic_stringbuf<Elem, Tr, Alloc> *rdbuf() const;
        basic_string<Elem, Tr, Alloc> str();
        void str(const basic_string<Elem, Tr, Alloc>& newstr);
        };Copy to clipboard

The template 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
`basic_stringbuf<Elem, Tr, Alloc>`,
with elements of type `Elem`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined
by the class `Tr`, and whose elements are allocated by
an allocator of class `Alloc`. The object stores an object of class
`basic_stringbuf<Elem, Tr, Alloc>`.

### `basic_stringstream::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `basic_stringstream::basic_stringstream`

    explicit basic_stringstream(
        ios_base::openmode mode =
            ios_base::in | ios_base::out);
    explicit basic_stringstream(
        const basic_string<Elem, Tr, Alloc>& str,
        ios_base::openmode mode =
             ios_base::in | ios_base::out);Copy to clipboard

The first constructor initializes the base class by calling
`basic_iostream(sb)`,
where `sb` is the stored object of class
`basic_stringbuf<Elem, Tr, Alloc>`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(mode)`.

The second constructor initializes the base class by calling
`basic_iostream(sb)`.
It also initializes `sb` by calling
`basic_stringbuf<Elem,
Tr, Alloc>(str, mode)`.

### `basic_stringstream::rdbuf`

    basic_stringbuf<Elem, Tr, Alloc> *rdbuf() constCopy to clipboard

The member function returns the address of the stored
stream buffer, of type pointer to
`basic_stringbuf<Elem,
Tr, Alloc>`.

### `basic_stringstream::str`

    basic_string<Elem, Tr, Alloc> str() const;
    void str(const basic_string<Elem, Tr, Alloc>& newstr);Copy to clipboard

The first member function returns
`rdbuf()->
str()`.
The second member function calls `rdbuf()-> str(newstr)`.

## `istringstream`

    typedef basic_istringstream<char> istringstream;Copy to clipboard

The type is a synonym for template class
[`basic_istringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_istringstream), specialized
for elements of type *char.*

## `ostringstream`

    typedef basic_ostringstream<char> ostringstream;Copy to clipboard

The type is a synonym for template class
[`basic_ostringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_ostringstream), specialized
for elements of type *char.*

## `stringbuf`

    typedef basic_stringbuf<char> stringbuf;Copy to clipboard

The type is a synonym for template class
[`basic_stringbuf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_stringbuf), specialized
for elements of type *char.*

## `stringstream`

    typedef basic_stringstream<char> stringstream;Copy to clipboard

The type is a synonym for template class
[`basic_stringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_stringstream), specialized
for elements of type *char.*

## `wistringstream`

    typedef basic_istringstream<wchar_t> wistringstream;Copy to clipboard

The type is a synonym for template class
[`basic_istringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_istringstream), specialized
for elements of type `wchar_t`.

## `wostringstream`

    typedef basic_ostringstream<wchar_t> wostringstream;Copy to clipboard

The type is a synonym for template class
[`basic_ostringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_ostringstream), specialized
for elements of type `wchar_t`.

## `wstringbuf`

    typedef basic_stringbuf<wchar_t> wstringbuf;Copy to clipboard

The type is a synonym for template class
[`basic_stringbuf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_stringbuf), specialized
for elements of type `wchar_t`.

## `wstringstream`

    typedef basic_stringstream<wchar_t> wstringstream;Copy to clipboard

The type is a synonym for template class
[`basic_stringstream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_sstream.html#basic_stringstream), specialized
for elements of type `wchar_t`.

* * *

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
 
<slist></slist> Next Topic

<stack></stack>