Boost "quoted" I/O manipulator

| # "Quoted" I/O Manipulators for Strings

"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:

>     std::cout << quoted("'Jack & Jill'", '&', '\'');  // outputs: '&'Jack && Jill&''

## Header <boost/io/quoted_manip.hpp> synopsis

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

© 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 08 March 2013