![]() |
"Quoted"
I/O Manipulators
|
|
"Quoted" I/O Manipulators for Strings are not yet accepted into Boost as public components. Thus the header file is currently located in <boost/io/detail/quoted_manip.hpp> |
C++ Standard library stream I/O for strings that contain embedded spaces can produce unexpected results. For example,
std::stringstream ss; std::string original = "fooled you"; std::string round_trip; ss << original; ss >> round_trip; std::cout << original; // outputs: fooled you std::cout << round_trip; // outputs: fooled assert(original == round_trip); // assert will fire
The Boost quoted stream I/O manipulator places delimiters, defaulted
to the double-quote ("), around strings on output, and strips off
the delimiters on input. This ensures strings with embedded spaces round-trip as
desired. For example,
std::stringstream ss; std::string original = "fooled you"; std::string round_trip; ss << quoted(original); ss >> quoted(round_trip); std::cout << quoted(original); // outputs: "fooled you" std::cout << round_trip; // outputs: fooled you assert(original == round_trip); // assert will not fire
If the string contains the delimiter character, on output that character will be preceded by an escape character, as will the escape character itself:
std::cout << quoted("'Jack & Jill'", '&', '\''); // outputs: '&'Jack && Jill&''
namespace boost
{
namespace io
{
// manipulator for const std::basic_string&
template <class Char, class Traits, class Alloc>
unspecified-type1 quoted(const std::basic_string<Char, Traits, Alloc>& string, Char escape='\\', Char delim='\"');
// manipulator for const C-string*
template <class Char>
unspecified-type2 quoted(const Char* string, Char escape='\\', Char delim='\"');
// manipulator for non-const std::basic_string&
template <class Char, class Traits, class Alloc>
unspecified-type3 quoted(std::basic_string<Char, Traits, Alloc>& string, Char escape='\\', Char delim='\"');
}
}
unspecified_type1, unspecified_type2,
and unspecified_type3 are implementation supplied
types with implementation supplied operator<<:
template <class Char, class Traits> std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os, constunspecified_typeN& proxy);Effects: Inserts characters into
os:
delim.- Each character in
string. If the character to be output is equal toescapeordelim, as determined byoperator==, first outputescape.delim.Remarks:
string,escape, anddelimhave the type and value of the corresponding arguments of the call to thequotedfunction that constructedproxy.Returns:
os.
unspecified_type3 is an implementation supplied
type with an implementation supplied operator>>:
template <class Char, class Traits> std::basic_istream<Char, Traits>& operator>>(std::basic_istream<Char, Traits>& is, constunspecified_type3& proxy);Effects: Extracts characters from
os:
- If the first character extracted is equal to delim, as determined by
operator==, then:
- Turn off the
skipwsflag.string.clear()- Until an unescaped
delimcharacter is reached oris.not_good(), extract characters fromosand append them tostring, except that if anescapeis reached, ignore it and append the next character tostring.- Discard the final
delimcharacter.- Restore the
skipwsflag to its original value.- Otherwise,
os >> string.Remarks:
string,escape, anddelimhave the type and value of the corresponding arguments of the call to thequotedfunction that constructedproxy.Returns:
is.
The quoted() stream manipulator emerged from discussions on the
Boost developers mailing list. Participants included Beman Dawes, Rob Stewart,
Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, Phil Richards,
and Rob Murray. Eric Niebler's suggestions provided the basis for the name and
form of the templates.
© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt
Revised 20 June 2010