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; }
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)
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_
i
stream
.explicit
basi
c
_istringstream
(
const
basic_string<charT,traits,Alloc>&
str,
ios_base::
o
penmode
which
=
ios_base::in)
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_
i
stream
.basic_stringbuf<charT,traits,Alloc
>*
rdbuf
()
const
basic_stringbuf
object.basic_string<charT,traits,Alloc>
str
()
const
rdbuf()->str
(
)
.void
str
(const
basic_string<charT,traits,Alloc>&
s)
rdbuf()->str(s)
.basic_stringstream class template, istringstream class, wistringstream class, basic_ifstream in <fstream>, basic_istream in <istream>
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)
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_
i
stream
.explicit
basi
c
_ostringstream
(
const
basic_string<charT,traits,Alloc>&
str,
ios_base::
o
penmode
which
=
ios_base::out)
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_
i
stream
.basic_stringbuf<charT,traits,Alloc
>*
rdbuf
()
const
basic_stringbuf
object.basic_string<charT,traits,Alloc>
str
()
const
rdbuf()->str
(
)
.void
str
(const
basic_string<charT,traits,Alloc>&
s)
rdbuf()->str(s)
.basic_stringstream class template, ostringstream class, wostringstream class, basic_ofstream in <fstream>, basic_ostream in <istream>
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::
o
penmode
mode
=
ios_base::in
|
ios_base::out)
mode
. The second version initializes the input string with str
if mode
&
io
s
_base::
i
n
is not zero, and initializes the output string with str
if mode
&
ios_base::
o
ut
is not zero.virtual int_type
overflow
(int_type c = traits::eof())
c
to the end of the output string as follows:c
is an end-of-file character (traits::eq_int_ty
pe
(c,
trait
s
::eof(
)
)
is true), nothing happens and a non-eof character is returned to indicate success.c
is not end-of-file, and there is a write position available, c
is appended to the output string by calling sputc(c)
.mode
allows writing (mode
&
ios_base::
o
ut
is not zero), the output string is extended by one character and c
is appended. If the mode
allows reading (mode
&
ios_base::
i
n
is not zero), the read end pointer egptr()
is set to point to one position past the end of the output string.c
for success or traits::eof
(
)
for failure.virtual
int_type
pbackfail
(int_type
c
=
traits::eof())
c
back onto the input string for reading as follows:c
is an end-of-file character (traits::eq_int_ty
pe
(c,
trait
s
::eof(
)
)
is true), and a putback position is available, gptr()
is set to gptr()
- 1.c
is not an end-of-file character, and there is a putback position available, and gptr()[-1]
is equal to c
, gptr()
is set to gptr()
- 1.c
is not an end-of-file character, and there is a putback position available, and the mode
allows writing (mode
&
ios_base::out
is not zero), gptr()
is set to gptr()
- 1, and *gptr()
is assigned c
.c
for success or trait
s
::eof
(
)
for failure. If c
is traits::eof(),
trait
s
::not_eof(c)
is returned for success.virtual
pos_type
seekoff
(off_type
off,
ios_base::
se
ekdir
way,
ios_base::
o
penmode
which
=
io
s
_base::i
n
|ios_base::
o
ut)
(which
&
(ios_base::in
|
ios_base::out)
:ios_base::in
, set the input position;ios_base::
o
ut
, set the output position;ios_base::
i
n
|
ios_base::
o
ut
, and way
is either beg
or end
, set input and output positions;pos_type(-1)
.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
(io
s
_base::
be
g
, ios_base::
c
ur
, 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_
t
ype
seekpos
(pos_type
s
p
,
ios_base::openmode
which
=
ios_base::in|i
o
s_base::out)
sp
. The input position is set if which
&
ios_base::
i
n
is not zero. The output position is set if which
&
io
s
_base::
o
ut
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
setbuf(0,
0)
has no effect. The result of any other call to setbuf
is implementation-defined.basic_string<charT,traits,Alloc>
str
()
const
mode
allows output (mode
&
io
s
_base::out
is not zero); otherwise it returns the input string.void
str
(
c
onst
basic_string<charT,traits,Alloc>&
s)
mode
&
ios_base::
i
n
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
()
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 tr
aits
::to_int_type(*gptr())
.stringbuf class, wstringbuf class, basic_filebuf in <fstream>, basic_streambuf in <streambuf>
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)
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_
i
stream
.explicit
basi
c
_stringstream
(
const
basic_string<charT,traits,Alloc>&
str,
ios_base::
o
penmode
which
=
ios_base::in|ios_base::out)
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_
i
stream
.basic_stringbuf<charT,traits,Alloc
>*
rdbuf
()
const
basic_stringbuf
object.basic_string<charT,traits,Alloc>
str
()
const
rdbuf()->str
(
)
.void
str
(const
basic_string<charT,traits,Alloc>&
s)
rdbuf()->str(s)
.basic_istringstream class template, basic_ostringstream class template, stringstream class, wstringstream class, basic_fstream in <fstream>, basic_iostream in <istream>
Input string stream
typedef basic_istringstream<char> istringstream;
The istringstream
class is a specialization of the basic_istringstream
template for char
characters.
basic_istringstream class template, wistringstream class, ifstream in <fstream>, istream in <istream>
Output string stream
typedef basic_ostringstream<char> ostringstream;
The ostringstream
class is a specialization of the basic_ostringstream
template for char
characters.
basic_ostringstream class template, wostringstream class, ofstream in <fstream>, ostream in <ostream>
Narrow character string buffer
typedef basic_stringbuf<char> stringbuf;
The stringbuf
class is a specialization of the basic_stringbuf
template for char
characters.
basic_stringbuf class template, wstringbuf class, filebuf in <fstream>, streambuf in <streambuf>
Input and output string stream
typedef basic_stringstream<char> stringstream;
The stringstream
class is a specialization of the basic_stringstream
template for char
characters.
basic_stringstream class template, wstringstream class, fstream in <fstream>, iostream in <istream>
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.
basic_istringstream class template, istringstream class, wifstream in <fstream>, wistream in <istream>
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.
basic_ostringstream class template, ostringstream class, wofstream in <fstream>, wostream in <ostream>
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.
basic_stringbuf class template, stringbuf class, wfilebuf in <fstream>, wstreambuf in <streambuf>
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.
basic_stringstream class template, stringstream class, wfstream in <fstream>, wiostream in <istream>