Hu Chunming / sip_server

quoted.adoc 4.23 KB

Quoted Manipulators, <boost/io/quoted.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 roundtrip;

ss << original;
ss >> roundtrip;

std::cout << original;   // outputs: fooled you
std::cout << roundtrip; // outputs: fooled

assert(original == roundtrip); // 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 roundtrip;

ss << quoted(original);
ss >> quoted(roundtrip);

std::cout << quoted(original); // outputs: "fooled you"
std::cout << roundtrip;       // outputs: fooled you

assert(original == roundtrip); // 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&''

Header synopsis

namespace boost {
namespace io {

template
`unspecified-type1`
quoted(const std::basic_string& string,
       Char escape='\\', Char delim='\"');

template
`unspecified-type2`
quoted(const Char* string, Char escape='\\', Char delim='\"');

template
`unspecified-type3`
quoted(std::basic_string& string,
       Char escape='\\', Char delim='\"');

} // io
} // boost

unspecified-type1, unspecified-type2, and unspecified-type3 are implementation supplied types with implementation supplied operator<<:

template
std::basic_ostream&
operator<<(std::basic_ostream& os,
           const `unspecified-typeN`& proxy);
Effects

Inserts characters into os:

  • delim

  • 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
std::basic_istream&
operator>>(std::basic_istream& 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.

Beman Dawes started the implementation of quoted() as a private detail header. Glen Fernandes updated the implementation and also made it public.

Glen Fernandes corrected the implementation to properly account for stream width and fill, and optimized it to write directly to the stream buffer.