projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
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" | |
| 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">"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 | |
| 42 | can produce unexpected results. For example,</p> | |
| 43 | <blockquote> | |
| 44 | <pre>std::stringstream ss; | |
| 45 | std::string original = "fooled you"; | |
| 46 | std::string round_trip; | |
| 47 | ||
| 48 | ss << original; | |
| 49 | ss >> round_trip; | |
| 50 | ||
| 51 | std::cout << original; // outputs: fooled you | |
| 52 | std::cout << 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>"</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 = "fooled you"; | |
| 63 | std::string round_trip; | |
| 64 | ||
| 65 | ss << quoted(original); | |
| 66 | ss >> quoted(round_trip); | |
| 67 | ||
| 68 | std::cout << quoted(original); // outputs: "fooled you" | |
| 69 | std::cout << 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 << 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, Char escape='\\', Char delim='\"'); | |
| 87 | ||
| 88 | // manipulator for const C-string* | |
| 89 | ||
| 90 | template <class Char> | |
| 91 | <b><i>unspecified-type2</i></b> quoted(const Char* string, Char escape='\\', Char delim='\"'); | |
| 92 | ||
| 93 | // manipulator for non-const std::basic_string& | |
| 94 | ||
| 95 | template <class Char, class Traits, class Alloc> | |
| 96 | <b><i>unspecified-type3</i></b> quoted(std::basic_string<Char, Traits, Alloc>& string, Char escape='\\', Char delim='\"'); | |
| 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<<</code>:</p> | |
| 102 | <blockquote> | |
| 103 | <pre>template <class Char, class Traits> | |
| 104 | std::basic_ostream<Char, Traits>& | |
| 105 | operator<<(std::basic_ostream<Char, Traits>& os, const <i><b><code>unspecified_typeN</code></b></i>& 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>></code>:</p> | |
| 121 | <blockquote> | |
| 122 | <pre>template <class Char, class Traits> | |
| 123 | std::basic_istream<Char, Traits>& | |
| 124 | operator>>(std::basic_istream<Char, Traits>& is, const <i><b><code>unspecified_type3</code></b></i>& 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 >> 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 |