13.42 <sstream>

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

See Chapter 9 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 8 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. See also <strstream> for classes that are similar to the string streams, except they work with arrays of narrow characters.

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-35 shows tostring, a simple use of ostringstream to convert a value to a string. (Think of tostring as the inverse of strtol and friends.)

Example 13-35. 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-36 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 that the order of the color elements matches the order needed by the program. The known color names are stored in a map.

Example 13-36. 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;
}

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 argument and then read from the string stream just as you would from any other input stream.

The following are the methods of basic_istringstream:

explicit basic_istringstream(ios_base::openmode which = ios_base::in)

Initializes an empty input string stream by constructing an internal basic_stringbuf object, passing which | ios_base::in to that object's constructor, and passing the address of the string buffer to the base-class constructor for basic_istream.

explicit basic_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 by constructing an internal basic_stringbuf object, passing str and which | ios_base::in to that object's 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 the buffer contents as a string, that is, rdbuf( )->str( ).

void str(const basic_string<charT,traits,Alloc>& s)

Calls rdbuf( )->str(s) to set the buffer contents.

See Also

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

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. You would then call the str member function to read the resulting string.

The following are the methods of basic_ostringstream:

explicit basic_ostringstream(ios_base::openmode which = ios_base::out)

Initializes an empty output string stream by constructing an internal basic_stringbuf object, passing which | ios_base::out to that object's constructor, and passing the address of the string buffer to the base-class constructor for basic_ostream.

explicit basic_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 by constructing an internal basic_stringbuf object, passing str and which | ios_base::out to that object's constructor, and passing the address of the string buffer to the base-class constructor for basic_ostream.

basic_stringbuf<charT,traits,Alloc>* rdbuf( ) const

Returns a pointer to the internal basic_stringbuf object.

basic_string<charT,traits,Alloc> str( ) const

Returns the buffer contents as a string, that is, rdbuf( )->str( ).

void str(const basic_string<charT,traits,Alloc>& s)

Calls rdbuf( )->str(s) to set the buffer contents.

See Also

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

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 single character buffer with separate positions for reading and writing. That is, the buffer has begin, next, and end pointers for reading and separate begin, next, and end pointers for writing. The begin pointer points to the start of a buffer, and the end pointer points to one past the end of the buffer. The next pointer points to the position where the next character will be read or written. Refer to basic_streambuf in <streambuf> for details about buffer 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)

Initializes the buffer with an empty string and remembers the mode.

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

Initializes the buffer with a copy of str and remembers the mode. If mode & ios_base::in is nonzero, the input position is initialized to read from the start of the buffer. If mode & ios_base::out is nonzero, the output position is initialized to overwrite the buffer.

virtual int_type overflow (int_type c = traits::eof( ))

Attempts to append c to the end of the buffer as follows:

• If c is an end-of-file character (c is traits::eof( )), nothing happens, and a non-end-of-file character is returned to indicate success.

• If c is not end-of-file, and a write position is available, c is appended to the buffer by calling sputc(c).

• If a write position is not available, and the mode allows writing (mode & ios_base::out is nonzero), the buffer is extended by one character and c is appended. If the mode allows reading (mode & ios_base::in is nonzero), the read end pointer egptr( ) is set to point to one position past the end of the buffer.

The return value is traits::not_eof(c) for success or traits::eof( ) for failure.

virtual int_type pbackfail(int_type c = traits::eof( ))

Attempts to push c back onto the buffer for reading as follows:

• If c is an end-of-file character (c is traits::eof( )), and a putback position is available, gptr( ) is set to gptr( ) - 1.

• If c is not an end-of-file character, and a putback position is available, and gptr( )[-1] is equal to c, gptr( ) is set to gptr( ) - 1.

• If c is not an end-of-file character, and a putback position is available, and the mode allows writing (mode & ios_base::out is nonzero), gptr( ) is set to gptr( ) - 1, and *gptr( ) is assigned c.

The return value is traits::not_eof(c) for success or traits::eof( ) for failure.

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 following are the possible results of this expression:

ios_base::in

Sets the input position

ios_base::out

Sets the output position

ios_base::in | ios_base::out, and way is either ios_base::beg or ios_base::end

Sets input and output positions

Otherwise

The function fails and returns pos_type(-1)

The new position is determined 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 buffer, 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 nonzero. The output position is set if which & ios_base::out is nonzero. 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, seekoff, seekpos, tellg, or tellp), the results are undefined.

virtual basic_streambuf<charT,traits>* setbuf(charT*, streamsize)

Calling setbuf(0, 0) has no effect other than to return this. The result of any other call to setbuf is implementation-defined.

basic_string<charT,traits,Alloc> str( ) const

Returns the contents of the buffer as a string. If the mode allows output (mode & ios_base::out is nonzero), the buffer contents are taken from the output positions; otherwise, the buffer contents are copied from the input positions.

void str(const basic_string<charT,traits,Alloc>& s)

Deallocates the current buffer if one exists and replaces it with a copy of s. If mode & ios_base::in is nonzero, the input positions are set to read from the start of the buffer. If mode & ios_base::out is nonzero, the output positions are set to overwrite the buffer.

virtual int_type underflow( )

Returns *gptr( ) if more input is available, that is, if there is a read position. Otherwise, the function returns traits::eof( ).

See Also

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

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. If you initialize the stream with a string and start writing, the output overwrites the string. You can switch between reading and writing at any time and set the read and write positions independently.

The following are the methods of basic_stringstream:

explicit basic_stringstream(ios_base::openmode which = ios_base::in | ios_base::out)

Initializes an empty string stream by constructing an internal basic_stringbuf object, passing which | ios_base::in | ios_base::out to that object's constructor and the address of the string buffer to the base-class constructor for basic_iostream.

explicit basic_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 by constructing an internal basic_stringbuf object, passing str and which | ios_base::in | ios_base::out to that object's constructor and the address of the string buffer to the base-class constructor for basic_iostream.

basic_stringbuf<charT,traits,Alloc>* rdbuf( ) const

Returns a pointer to the internal basic_stringbuf object.

basic_string<charT,traits,Alloc> str( ) const

Returns the buffer contents as a string, that is, rdbuf( )->str( ).

void str(const basic_string<charT,traits,Alloc>& s)

Calls rdbuf( )->str(s) to set the buffer contents.

See Also

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

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>

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>

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>

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>

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>

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>

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>

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>