Draft 2002-08-19

<sstream>

The <sstream> header declares classes and other types for reading from strings and writing to strings in the same manner as reading from and writing to files.

See Chapter 10 for a general discussion of I/O, Chapter 1 for more information about character sets, and the <iostream> section in this chapter for information about the base class templates required by the stringstream class templates. Refer to Chapter 9 for information about traits in general and to the <string> section in this chapter for detailed information about the char_traits template. Refer to the <streambuf> section in this chapter for information about the basic_streambuf template.

To read from a string, use istringstream; for writing, use ostringstream; for reading and writing, use stringstream. For wide character I/O, use wistringstream, wostringstream, or wstringstream. Example 13-37 shows a simple use of ostringstream to convert a value to a string. (Think of it as the inverse of strtol and friends.)

Example 13-37: Converting a value to a string.

template<typename T>
std::string tostring(const T& x)
{
  std::ostringstream out;
  out << x;
  return out.str();
}

Example 13-38 shows a use of istringstream to interpret HTML colors. In HTML, a color can be a name, such as "white", or a hexadecimal digit string that begins with '#'. The digit string is interpreted as a triplet of red, green, and blue color elements, each expressed as two hexadecimal digits. For the sake of simplicity, the example omits error-handling and assumes the order of the color elements matches the order needed by the program. The known color names are stored in a map.

Example 13-38: Interpreting an HTML color string.

typedef std::map<std::string, unsigned long> colormap;
colormap colors;

unsigned long get_color(const std::string& text)
{
  unsigned long rgb;
  colormap::iterator i = colors.find(text);
  if (i != colors.end())
    return i->second;
  else if (text.length() == 0)
    return 0;
  else {
    std::istringstream in(text);
    if (in.peek() == '#')
      in.ignore();
    in >> std::noskipws >> std::hex >> rgb;
    if (in)
      return rgb;
    else
      return 0;
  }
}

void initcolors(colormap& colors)
{
  ...
  colors["black"] = 0x000000;
  colors["blue"]  = 0x0000FF;
  colors["green"] = 0x00FF00;
  colors["red"]   = 0xFF0000;
  colors["white"] = 0xFFFFFF;
}

basic_istringstream

Base class for input string streams

template <class charT, class traits = char_traits<charT>,
   class Alloc = allocator<charT> >
class basic_istringstream: public basic_istream<charT,traits>
{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;

  explicit basic_istringstream(ios_base::openmode which =
    ios_base::in);
  explicit basic_istringstream(
    const basic_string<charT,traits,Alloc>& str,
    ios_base::openmode which = ios_base::in);

  basic_stringbuf<charT,traits,Alloc>* rdbuf() const;
  basic_string<charT,traits,Alloc> str() const;
  void str(const basic_string<charT,traits,Alloc>& s);
};

The basic_istringstream class template is the base class for input string streams. Typically, you would construct an istringstream with a string and then reads from the string stream just as you would read from any other istream.

Following are the methods of basic_istringstream.

explicit basic_istringstream (ios_base::openmode which =
ios_base::in)
Initializes an empty input string stream. It constructs an internal basic_stringbuf object, passing which | ios_base::in to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
explicit basi c _istringstream (
const basic_string<charT,traits,Alloc>& str,
ios_base::openmode which = ios_base::in)
Initializes a string stream with str as the initial string contents. It constructs an internal basic_stringbuf object, passing str and which | ios_base::in to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
basic_stringbuf<charT,traits,Alloc>* rdbuf () const
Returns a pointer to the internal basic_stringbuf object.
basic_string<charT,traits,Alloc> str () const
Returns rdbuf()->str().
void str (const basic_string<charT,traits,Alloc>& s)
Calls rdbuf()->str(s).

See Also

basic_stringstream class template, istringstream class, wistringstream class, basic_ifstream in <fstream>, basic_istream in <istream>

basic_ostringstream

Base class for output string streams

template <class charT, class traits = char_traits<charT>,
  class Alloc = allocator<charT> >
class basic_ostringstream: public basic_ostream<charT,traits>
{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;

  explicit basic_ostringstream(ios_base::openmode which =
    ios_base::out);
 explicit basic_ostringstream(
    const basic_string<charT,traits,Alloc>& str,
    ios_base::openmode which = ios_base::out);

  basic_stringbuf<charT,traits,Alloc>* rdbuf() const;
  basic_string<charT,traits,Alloc> str() const;
  void str(const basic_string<charT,traits,Alloc>& s);
};

The basic_ostringstream class template is the base class for output string streams. Typically, you would construct an ostringstream with no string, and let the string stream allocate the string as you write to the stream. Then use the str() member to read the resulting string.

Following are the methods of basic_ostringstream.

explicit basic_ostringstream (ios_base::openmode which =
ios_base::out)
Initializes an empty output string stream. It constructs an internal basic_stringbuf object, passing which | ios_base::out to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
explicit basi c _ostringstream (
const basic_string<charT,traits,Alloc>& str,
ios_base::openmode which = ios_base::out)
Initializes a string stream with str as the initial string contents. It constructs an internal basic_stringbuf object, passing str and which | ios_base::out to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
basic_stringbuf<charT,traits,Alloc>* rdbuf () const
Returns a pointer to the internal basic_stringbuf object.
basic_string<charT,traits,Alloc> str () const
Returns rdbuf()->str().
void str (const basic_string<charT,traits,Alloc>& s)
Calls rdbuf()->str(s).

See Also

basic_stringstream class template, ostringstream class, wostringstream class, basic_ofstream in <fstream>, basic_ostream in <istream>

basic_stringbuf

Base class for string buffers

template <class charT, class traits = char_traits<charT>,
   class Alloc = allocator<charT> >
class basic_stringbuf : public basic_streambuf<charT,traits>
{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;
  explicit basic_stringbuf(ios_base::openmode mode =
    ios_base::in | ios_base::out);
  explicit basic_stringbuf(
    const basic_string<charT,traits,Alloc>& str,
    ios_base::openmode mode = ios_base::in | ios_base::out);
  basic_string<charT,traits,Alloc> str() const;
  void str(const basic_string<charT,traits,Alloc>& s);
protected:
  virtual int_type underflow();
  virtual int_type pbackfail(int_type c = traits::eof());
  virtual int_type overflow (int_type c = traits::eof());
  virtual basic_streambuf<charT,traits>*
    setbuf(charT*, streamsize);
  virtual pos_type seekoff(off_type off,
    ios_base::seekdir way,
    ios_base::openmode which = ios_base::in | ios_base::out);
  virtual pos_type seekpos(pos_type sp,
    ios_base::openmode which = ios_base::in | ios_base::out);
};

The basic_stringbuf class template implements a stream buffer for string-based streams. A string buffer maintains a string with separate input and output positions.

Refer to basic_streambuf in <streambuf> for information about read positions and write positions.

In the following descriptions of the member functions of basic_stringbuf, mode refers to a private copy of the mode parameter that is passed to the constructors. The implementation is not required to have such a data member, but the descriptions below are clearer with the assumption that it exists.

explicit basic_stringbuf (ios_base::openmode mode =
ios_base::in | ios_base::out)
explicit basic_stringbuf (
const basic_string<charT,traits,Alloc>& str,
ios_base::openmode mode = ios_base::in | ios_base::out)
Initializes the string buffer and remembers the mode. The second version initializes the input string with str if mode & ios_base::in is not zero, and initializes the output string with str if mode & ios_base::out is not zero.
virtual int_type overflow (int_type c = traits::eof())
Attempts to append c to the end of the output string as follows:
The return value is c for success or traits::eof() for failure.
virtual int_type pbackfail (int_type c = traits::eof())
Attempts to push c back onto the input string for reading as follows:
The return value is c for success or traits::eof() for failure. If c is traits::eof(), traits::not_eof(c) is returned for success.
virtual pos_type seekoff (off_type off,
ios_base::seekdir way,
ios_base::openmode which = ios_base::in|ios_base::out)
Sets the stream position. The input position, output position, or both can be set, depending on (which & (ios_base::in | ios_base::out):
The new position is determines as an offset off, which is added to the position at the start of the stream, the current position, or at the end of the stream, depending on way (ios_base::beg, ios_base::cur, or ios_base::end). If the desired position is negative or past the end of the string, the function fails and returns pos_type(-1). If the function succeeds, it returns the new position.
virtual pos_type seekpos (pos_type sp,
ios_base::openmode which = ios_base::in|ios_base::out)
Sets the stream position to sp. The input position is set if which & ios_base::in is not zero. The output position is set if which & ios_base::out is not zero. If sp is not a valid position, or if neither the input nor the output position is set, seekpos fails and pos_type(-1) is returned. The return value is sp for success. If sp was not returned from a prior call to a positioning function (that is, seekof, seekpos, tellg, or tellp) the results are undefined.
virtual basic_streambuf<charT,traits>*
setbu f(charT*, streamsize)

portability icon

Calling setbuf(0, 0) has no effect. The result of any other call to setbuf is implementation-defined.
basic_string<charT,traits,Alloc> str () const
Returns the output string if the mode allows output (mode & ios_base::out is not zero); otherwise it returns the input string.
void str (const basic_string<charT,traits,Alloc>& s)
Deallocates any existing input and output strings. If mode & ios_base::in is not zero, s is copied to the input string. If mode & ios_base::out is not zero, s is copied to the output string.
virtual int_type underflow ()
The underflow function can't get more input from an external source, so it returns traits::eof() if no more input is available. If there is a read position, underflow returns traits::to_int_type(*gptr()).

See Also

stringbuf class, wstringbuf class, basic_filebuf in <fstream>, basic_streambuf in <streambuf>

basic_stringstream

Base class for input and output string streams

template <class charT, class traits = char_traits<charT>,
  class Alloc = allocator<charT> >
class basic_stringstream: public basic_iostream<charT,traits>
{
public:
  typedef charT char_type;
  typedef typename traits::int_type int_type;
  typedef typename traits::pos_type pos_type;
  typedef typename traits::off_type off_type;
  typedef traits traits_type;

  explicit basic_stringstream(ios_base::openmode which =
    ios_base::out|ios_base::in);
  explicit basic_stringstream(
    const basic_string<charT,traits,Alloc>& str,
    ios_base::openmode which = ios_base::out|ios_base::in);

  basic_stringbuf<charT,traits,Alloc>* rdbuf() const;
  basic_string<charT,traits,Alloc> str() const;
  void str(const basic_string<charT,traits,Alloc>& str);
};

The basic_stringstream class template is the base class for string streams that permit input and output. You can start with an empty string and write to the stream, or start with a string and read from the stream. You can switch between reading and writing at any time.

Following are the methods of basic_ostringstream.

explicit basic_stringstream (ios_base::openmode which =
ios_base::in | ios_base::out)
Initializes an empty string stream. It constructs an internal basic_stringbuf object, passing which | ios_base::in | ios_base::out to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
explicit basi c _stringstream (
const basic_string<charT,traits,Alloc>& str,
ios_base::openmode which = ios_base::in|ios_base::out)
Initializes a string stream with str as the initial string contents. It constructs an internal basic_stringbuf object, passing str and which | ios_base::in | ios_base::out to the constructor, and passing the address of the string buffer to the base class constructor for basic_istream.
basic_stringbuf<charT,traits,Alloc>* rdbuf () const
Returns a pointer to the internal basic_stringbuf object.
basic_string<charT,traits,Alloc> str () const
Returns rdbuf()->str().
void str (const basic_string<charT,traits,Alloc>& s)
Calls rdbuf()->str(s).

See Also

basic_istringstream class template, basic_ostringstream class template, stringstream class, wstringstream class, basic_fstream in <fstream>, basic_iostream in <istream>

istringstream

Input string stream

typedef basic_istringstream<char> istringstream;

The istringstream class is a specialization of the basic_istringstream template for char characters.

See Also

basic_istringstream class template, wistringstream class, ifstream in <fstream>, istream in <istream>

ostringstream

Output string stream

typedef basic_ostringstream<char> ostringstream;

The ostringstream class is a specialization of the basic_ostringstream template for char characters.

See Also

basic_ostringstream class template, wostringstream class, ofstream in <fstream>, ostream in <ostream>

stringbuf

Narrow character string buffer

typedef basic_stringbuf<char> stringbuf;

The stringbuf class is a specialization of the basic_stringbuf template for char characters.

See Also

basic_stringbuf class template, wstringbuf class, filebuf in <fstream>, streambuf in <streambuf>

stringstream

Input and output string stream

typedef basic_stringstream<char> stringstream;

The stringstream class is a specialization of the basic_stringstream template for char characters.

See Also

basic_stringstream class template, wstringstream class, fstream in <fstream>, iostream in <istream>

wistringstream

Wide input string stream

typedef basic_istringstream<wchar_t> wistringstream;

The wistringstream class is a specialization of the basic_istringstream template for wchar_t characters.

See Also

basic_istringstream class template, istringstream class, wifstream in <fstream>, wistream in <istream>

wostringstream

Wide output string stream

typedef basic_ostringstream<wchar_t> wostringstream;

The wostringstream class is a specialization of the basic_ostringstream template for wchar_t characters.

See Also

basic_ostringstream class template, ostringstream class, wofstream in <fstream>, wostream in <ostream>

wstringbuf

Wide character string buffer

typedef basic_stringbuf<wchar_t> wstringbuf;

The wstringbuf class is a specialization of the basic_stringbuf template for wchar_t characters.

See Also

basic_stringbuf class template, stringbuf class, wfilebuf in <fstream>, wstreambuf in <streambuf>

wstringstream

Wide input and output string stream

typedef basic_stringstream<wchar_t> wstringstream;

The wstringstream class is a specialization of the basic_stringstream template for wchar_t characters.

See Also

basic_stringstream class template, stringstream class, wfstream in <fstream>, wiostream in <istream>