1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4<html> 5<head> 6 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> 7 <title>Boost "quoted" I/O manipulator</title> 8 <meta name="generator" content="Microsoft FrontPage 5.0" /> 9 <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css" /> 10</head> 11 12<body> 13 14<table border="0" cellpadding="5" cellspacing="0" 15style="border-collapse: collapse"> 16 <tbody> 17 <tr> 18 <td width="277"><a href="../../../index.htm"><img 19 src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" 20 width="300" height="86" border="0" /></a></td> 21 <td> 22 <h1 align="center">"Quoted" 23 I/O Manipulators<br> 24 for Strings</h1> 25 </td> 26 </tr> 27 </tbody> 28</table> 29 30<table border="1" cellpadding="5" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111"> 31 <tr> 32 <td> 33 <p align="center"><b>"Quoted" 34 I/O Manipulators 35 for Strings are not yet accepted into Boost as public components. Thus the 36 header file is currently located in <boost/io/detail/quoted_manip.hpp></b></td> 37 </tr> 38</table> 39 40<h2>Introduction</h2> 41<p>C++ Standard library stream I/O for strings that contain embedded spaces 42can produce unexpected results. For example,</p> 43<blockquote> 44 <pre>std::stringstream ss; 45std::string original = "fooled you"; 46std::string round_trip; 47 48ss << original; 49ss >> round_trip; 50 51std::cout << original; // outputs: fooled you 52std::cout << round_trip; // outputs: fooled 53 54assert(original == round_trip); // assert will fire</pre> 55</blockquote> 56<p>The Boost <code>quoted</code> stream I/O manipulator places delimiters, defaulted 57to the double-quote (<code>"</code>), around strings on output, and strips off 58the delimiters on input. This ensures strings with embedded spaces round-trip as 59desired. For example,</p> 60<blockquote> 61 <pre>std::stringstream ss; 62std::string original = "fooled you"; 63std::string round_trip; 64 65ss << quoted(original); 66ss >> quoted(round_trip); 67 68std::cout << quoted(original); // outputs: "fooled you" 69std::cout << round_trip; // outputs: fooled you 70 71assert(original == round_trip); // assert will not fire</pre> 72</blockquote> 73<p>If the string contains the delimiter character, on output that character will 74be preceded by an escape character, as will the escape character itself:</p> 75<blockquote> 76 <pre>std::cout << quoted("'Jack & Jill'", '&', '\''); // outputs: '&'Jack && Jill&''</pre> 77</blockquote> 78<h2>Header <a href="../../../boost/io/detail/quoted_manip.hpp"><boost/io/quoted_manip.hpp></a> synopsis</h2> 79<pre>namespace boost 80{ 81 namespace io 82 { 83 // manipulator for const std::basic_string& 84 85 template <class Char, class Traits, class Alloc> 86 <b><i>unspecified-type1</i></b> quoted(const std::basic_string<Char, Traits, Alloc>& string, 87 Char escape='\\', Char delim='\"'); 88 89 // manipulator for const C-string* 90 91 template <class Char> 92 <b><i>unspecified-type2</i></b> quoted(const Char* string, 93 Char escape='\\', Char delim='\"'); 94 95 // manipulator for non-const std::basic_string& 96 97 template <class Char, class Traits, class Alloc> 98 <b><i>unspecified-type3</i></b> quoted(std::basic_string<Char, Traits, Alloc>& string, 99 Char escape='\\', Char delim='\"'); 100 } 101}</pre> 102<p><i><b><code>unspecified_type1</code></b></i>, <i><b><code>unspecified_type2</code></b></i>, 103and <i><b><code>unspecified_type3</code></b></i> are implementation supplied 104types with implementation supplied <code>operator<<</code>:</p> 105<blockquote> 106 <pre>template <class Char, class Traits> 107 std::basic_ostream<Char, Traits>& 108 operator<<(std::basic_ostream<Char, Traits>& os, const <i><b><code>unspecified_typeN</code></b></i>& proxy);</pre> 109<p><i>Effects:</i> Inserts characters into <code>os</code>:</p> 110 <ul> 111 <li><code>delim</code>.</li> 112 <li>Each character in <code>string</code>. If the character to be output is 113 equal to <code>escape</code> or <code>delim</code>, as determined by <code> 114 operator==</code>, first output <code>escape</code>. </li> 115 <li><code>delim</code>.</li> 116 </ul> 117<p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code> 118have the type and value of the corresponding arguments of the call to the <code> 119quoted</code> function that constructed <code>proxy</code>.</p> 120<p><i>Returns:</i> <code>os</code>. </p> 121</blockquote> 122<p><i><b><code>unspecified_type3</code></b></i> is an implementation supplied 123type with an implementation supplied <code>operator>></code>:</p> 124<blockquote> 125 <pre>template <class Char, class Traits> 126 std::basic_istream<Char, Traits>& 127 operator>>(std::basic_istream<Char, Traits>& is, const <i><b><code>unspecified_type3</code></b></i>& proxy);</pre> 128<p><i>Effects:</i> Extracts characters from <code>os</code>:</p> 129 <ul> 130 <li>If the first character extracted is equal to delim, as determined by 131 <code>operator==</code>, then:<ul> 132 <li>Turn off the <code>skipws</code> flag.</li> 133 <li><code>string.clear()</code></li> 134 <li>Until an unescaped <code>delim</code> character is reached or <code> 135 is.not_good()</code>, extract 136 characters from <code>os</code> and append them to <code>string</code>, 137 except that if an <code>escape</code> is reached, ignore it and append the 138 next character to <code>string</code>.</li> 139 <li>Discard the final <code>delim</code> character.</li> 140 <li>Restore the <code>skipws</code> flag to its original value.</li> 141 </ul> 142 </li> 143 <li>Otherwise, <code>os >> string</code>.</li> 144 </ul> 145<p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code> 146have the type and value of the corresponding arguments of the call to the <code> 147quoted</code> function that constructed <code>proxy</code>.</p> 148<p><i>Returns:</i> <code>is</code>. </p> 149</blockquote> 150<h2>Acknowledgements</h2> 151<p>The <code>quoted()</code> stream manipulator emerged from discussions on the 152Boost developers mailing list. Participants included Beman Dawes, Rob Stewart, 153Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, Phil Richards, 154and Rob Murray. Eric Niebler's suggestions provided the basis for the name and 155form of the templates. </p> 156<hr> 157<p>� Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010</p> 158<p>Distributed under the Boost Software License, Version 1.0. See 159<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p> 160<p>Revised 161<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->08 March 2013<!--webbot bot="Timestamp" endspan i-checksum="27284" --></p> 162 163</body> 164</html>
