ceph/src/boost/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, Char escape='\\', Char delim='\&quot;');
  87
  88     // manipulator for const C-string*
  89
  90     template &lt;class Char&gt;
  91     <b><i>unspecified-type2</i></b> quoted(const Char* string, Char escape='\\', Char delim='\&quot;');
  92
  93     // manipulator for non-const std::basic_string&amp;
  94
  95     template &lt;class Char, class Traits, class Alloc&gt;
  96     <b><i>unspecified-type3</i></b> quoted(std::basic_string&lt;Char, Traits, Alloc&gt;&amp; string, Char escape='\\', Char delim='\&quot;');
  97   }
  98 }</pre>
  99 <p><i><b><code>unspecified_type1</code></b></i>, <i><b><code>unspecified_type2</code></b></i>,
 100 and <i><b><code>unspecified_type3</code></b></i> are implementation supplied
 101 types with implementation supplied <code>operator&lt;&lt;</code>:</p>
 102 <blockquote>
 103   <pre>template &lt;class Char, class Traits&gt;
 104   std::basic_ostream&lt;Char, Traits&gt;&amp;
 105     operator&lt;&lt;(std::basic_ostream&lt;Char, Traits&gt;&amp; os, const <i><b><code>unspecified_typeN</code></b></i>&amp; proxy);</pre>
 106 <p><i>Effects:</i> Inserts characters into <code>os</code>:</p>
 107   <ul>
 108     <li><code>delim</code>.</li>
 109     <li>Each character in <code>string</code>. If the character to be output is
 110     equal to <code>escape</code> or <code>delim</code>, as determined by <code>
 111     operator==</code>, first output <code>escape</code>. </li>
 112     <li><code>delim</code>.</li>
 113   </ul>
 114 <p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code>
 115 have the type and value of the corresponding arguments of the call to the <code>
 116 quoted</code> function that constructed <code>proxy</code>.</p>
 117 <p><i>Returns:</i> <code>os</code>. </p>
 118 </blockquote>
 119 <p><i><b><code>unspecified_type3</code></b></i> is an implementation supplied
 120 type with an implementation supplied <code>operator&gt;&gt;</code>:</p>
 121 <blockquote>
 122   <pre>template &lt;class Char, class Traits&gt;
 123   std::basic_istream&lt;Char, Traits&gt;&amp;
 124     operator&gt;&gt;(std::basic_istream&lt;Char, Traits&gt;&amp; is, const <i><b><code>unspecified_type3</code></b></i>&amp; proxy);</pre>
 125 <p><i>Effects:</i> Extracts characters from <code>os</code>:</p>
 126   <ul>
 127     <li>If the first character extracted is equal to delim, as determined by
 128     <code>operator==</code>, then:<ul>
 129       <li>Turn off the <code>skipws</code> flag.</li>
 130       <li><code>string.clear()</code></li>
 131       <li>Until an unescaped <code>delim</code> character is reached or <code>
 132       is.not_good()</code>, extract
 133       characters from <code>os</code> and append them to <code>string</code>,
 134       except that if an <code>escape</code> is reached, ignore it and append the
 135       next character to <code>string</code>.</li>
 136       <li>Discard the final <code>delim</code> character.</li>
 137       <li>Restore the <code>skipws</code> flag to its original value.</li>
 138     </ul>
 139     </li>
 140     <li>Otherwise, <code>os &gt;&gt; string</code>.</li>
 141   </ul>
 142 <p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code>
 143 have the type and value of the corresponding arguments of the call to the <code>
 144 quoted</code> function that constructed <code>proxy</code>.</p>
 145 <p><i>Returns:</i> <code>is</code>. </p>
 146 </blockquote>
 147 <h2>Acknowledgements</h2>
 148 <p>The <code>quoted()</code> stream manipulator emerged from discussions on the
 149 Boost developers mailing list. Participants included Beman Dawes, Rob Stewart,
 150 Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, Phil Richards,
 151 and Rob Murray. Eric Niebler's suggestions provided the basis for the name and
 152 form of the templates. </p>
 153 <hr>
 154 <p>© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010</p>
 155 <p>Distributed under the Boost Software License, Version 1.0. See
 156 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
 157 <p>Revised
 158 <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->20 June 2010<!--webbot bot="Timestamp" endspan i-checksum="17544" --></p>
 159
 160 </body>
 161 </html>