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

basic_istringstream class template

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

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

13.42 <sstream>

Example 13-35. Converting a value to a string

Example 13-36. Interpreting an HTML color string

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also