<sstream>

Include the 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;
    };

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());
    };

The template class describes a stream buffer that controls the transmission of elements of type Elem, whose character traits 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 is accessible.
• If mode & ios_base::out is nonzero, the output buffer is accessible.

basic_stringbuf::allocator_type

typedef Alloc allocator_type;

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);

The first constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores mode as the stringbuf mode.

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.

basic_stringbuf::char_type

typedef Elem char_type;

The type is a synonym for the template parameter Elem.

basic_stringbuf::int_type

typedef typename traits_type::int_type int_type;

The type is a synonym for traits_type::int_type.

basic_stringbuf::off_type

typedef typename traits_type::off_type off_type;

The type is a synonym for traits_type::off_type.

basic_stringbuf::overflow

virtual int_type overflow(int_type meta =
    traits_type::eof());

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. 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.
• 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.)

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());

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 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 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 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;

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);

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. If mode & ios_base::out is nonzero, the function alters the next position to write in the output buffer. 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);

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. If mode & ios_base::out is nonzero, the function alters the next position to write in the output buffer. 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);

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 mode:

• If mode & ios_base::out is nonzero and an output buffer 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 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;

The type is a synonym for the template parameter Tr.

basic_stringbuf::underflow

virtual int_type underflow();

The protected virtual member function endeavors to extract the current element byte from the input buffer, 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 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);
    };

The template class describes an object that controls extraction of elements and encoded objects from a stream buffer of class basic_stringbuf<Elem, Tr, Alloc>, with elements of type Elem, whose character traits 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;

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);

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() const

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);

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:
    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);
    };

The template class describes an object that controls insertion of elements and encoded objects into a stream buffer of class basic_stringbuf<Elem, Tr, Alloc>, with elements of type Elem, whose character traits 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;

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);

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() const

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);

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);
    };

The template class describes an object that controls insertion and extraction of elements and encoded objects using a stream buffer of class basic_stringbuf<Elem, Tr, Alloc>, with elements of type Elem, whose character traits 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;

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);

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() const

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);

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

istringstream

typedef basic_istringstream<char> istringstream;

The type is a synonym for template class basic_istringstream, specialized for elements of type char.

ostringstream

typedef basic_ostringstream<char> ostringstream;

The type is a synonym for template class basic_ostringstream, specialized for elements of type char.

stringbuf

typedef basic_stringbuf<char> stringbuf;

The type is a synonym for template class basic_stringbuf, specialized for elements of type char.

stringstream

typedef basic_stringstream<char> stringstream;

The type is a synonym for template class basic_stringstream, specialized for elements of type char.

wistringstream

typedef basic_istringstream<wchar_t> wistringstream;

The type is a synonym for template class basic_istringstream, specialized for elements of type wchar_t.

wostringstream

typedef basic_ostringstream<wchar_t> wostringstream;

The type is a synonym for template class basic_ostringstream, specialized for elements of type wchar_t.

wstringbuf

typedef basic_stringbuf<wchar_t> wstringbuf;

The type is a synonym for template class basic_stringbuf, specialized for elements of type wchar_t.

wstringstream

typedef basic_stringstream<wchar_t> wstringstream;

The type is a synonym for template class basic_stringstream, specialized for elements of type wchar_t.

See also the Table of Contents and the Index.

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