"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>
+
+
+
+
Introduction
+
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:
Each character in string. If the character to be output is
+ equal to escape or delim, as determined by
+ operator==, first output escape.
+
delim.
+
+
Remarks:string, escape, and delim
+have the type and value of the corresponding arguments of the call to the
+quoted function that constructed proxy.
+
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, const unspecified_type3& proxy);
+
Effects: Extracts characters from os:
+
+
If the first character extracted is equal to delim, as determined by
+ operator==, then:
+
Turn off the skipws flag.
+
string.clear()
+
Until an unescaped delim character is reached or
+ is.not_good(), extract
+ characters from os and append them to string,
+ except that if an escape is reached, ignore it and append the
+ next character to string.
+
Discard the final delim character.
+
Restore the skipws flag to its original value.
+
+
+
Otherwise, os >> string.
+
+
Remarks:string, escape, and delim
+have the type and value of the corresponding arguments of the call to the
+quoted function that constructed proxy.
+
Returns:is.
+
+
Acknowledgements
+
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.
