Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.

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

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:

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 20 June 2010