libs/io/doc/quoted_manip.html

   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 &quot;quoted&quot; 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"
  15 style="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">&quot;Quoted&quot;
  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>&quot;Quoted&quot;
  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 &lt;boost/io/detail/quoted_manip.hpp&gt;</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
  42 can produce unexpected results. For example,</p>
  43 <blockquote>
  44   <pre>std::stringstream ss;
  45 std::string original = &quot;fooled you&quot;;
  46 std::string round_trip;
  47
  48 ss &lt;&lt; original;
  49 ss &gt;&gt; round_trip;
  50
  51 std::cout &lt;&lt; original;   // outputs: fooled you
  52 std::cout &lt;&lt; round_trip; // outputs: fooled
  53
  54 assert(original == round_trip); // assert will fire</pre>
  55 </blockquote>
  56 <p>The Boost <code>quoted</code> stream I/O manipulator places delimiters, defaulted
  57 to the double-quote (<code>&quot;</code>), around strings on output, and strips off
  58 the delimiters on input. This ensures strings with embedded spaces round-trip as
  59 desired. For example,</p>
  60 <blockquote>
  61   <pre>std::stringstream ss;
  62 std::string original = &quot;fooled you&quot;;
  63 std::string round_trip;
  64
  65 ss &lt;&lt; quoted(original);
  66 ss &gt;&gt; quoted(round_trip);
  67
  68 std::cout &lt;&lt; quoted(original); // outputs: &quot;fooled you&quot;
  69 std::cout &lt;&lt; round_trip;       // outputs: fooled you
  70
  71 assert(original == round_trip); // assert will not fire</pre>
  72 </blockquote>
  73 <p>If the string contains the delimiter character, on output that character will
  74 be preceded by an escape character, as will the escape character itself:</p>
  75 <blockquote>
  76   <pre>std::cout &lt;&lt; quoted(&quot;'Jack &amp; Jill'&quot;, '&amp;', '\'');  // outputs: '&amp;'Jack &amp;&amp; Jill&amp;''</pre>
  77 </blockquote>
  78 <h2>Header <a href="../../../boost/io/detail/quoted_manip.hpp">&lt;boost/io/quoted_manip.hpp&gt;</a> synopsis</h2>
  79 <pre>namespace boost
  80 {
  81   namespace io
  82   {
  83     // manipulator for const std::basic_string&amp;
  84
  85     template &lt;class Char, class Traits, class Alloc&gt;
  86     <b><i>unspecified-type1</i></b> quoted(const std::basic_string&lt;Char, Traits, Alloc&gt;&amp; string,
  87                              Char escape='\\', Char delim='\&quot;');
  88
  89     // manipulator for const C-string*
  90
  91     template &lt;class Char&gt;
  92     <b><i>unspecified-type2</i></b> quoted(const Char* string,
  93                              Char escape='\\', Char delim='\&quot;');
  94
  95     // manipulator for non-const std::basic_string&amp;
  96
  97     template &lt;class Char, class Traits, class Alloc&gt;
  98     <b><i>unspecified-type3</i></b> quoted(std::basic_string&lt;Char, Traits, Alloc&gt;&amp; string,
  99                              Char escape='\\', Char delim='\&quot;');
 100   }
 101 }</pre>
 102 <p><i><b><code>unspecified_type1</code></b></i>, <i><b><code>unspecified_type2</code></b></i>,
 103 and <i><b><code>unspecified_type3</code></b></i> are implementation supplied
 104 types with implementation supplied <code>operator&lt;&lt;</code>:</p>
 105 <blockquote>
 106   <pre>template &lt;class Char, class Traits&gt;
 107   std::basic_ostream&lt;Char, Traits&gt;&amp;
 108     operator&lt;&lt;(std::basic_ostream&lt;Char, Traits&gt;&amp; os, const <i><b><code>unspecified_typeN</code></b></i>&amp; 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>
 118 have the type and value of the corresponding arguments of the call to the <code>
 119 quoted</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
 123 type with an implementation supplied <code>operator&gt;&gt;</code>:</p>
 124 <blockquote>
 125   <pre>template &lt;class Char, class Traits&gt;
 126   std::basic_istream&lt;Char, Traits&gt;&amp;
 127     operator&gt;&gt;(std::basic_istream&lt;Char, Traits&gt;&amp; is, const <i><b><code>unspecified_type3</code></b></i>&amp; 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 &gt;&gt; string</code>.</li>
 144   </ul>
 145 <p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code>
 146 have the type and value of the corresponding arguments of the call to the <code>
 147 quoted</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
 152 Boost developers mailing list. Participants included Beman Dawes, Rob Stewart,
 153 Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, Phil Richards,
 154 and Rob Murray. Eric Niebler's suggestions provided the basis for the name and
 155 form 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>