123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164 |
- <?xml version="1.0" encoding="iso-8859-1"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <html>
- <head>
- <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
- <title>Boost "quoted" I/O manipulator</title>
- <meta name="generator" content="Microsoft FrontPage 5.0" />
- <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css" />
- </head>
- <body>
- <table border="0" cellpadding="5" cellspacing="0"
- style="border-collapse: collapse">
- <tbody>
- <tr>
- <td width="277"><a href="../../../index.htm"><img
- src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle"
- width="300" height="86" border="0" /></a></td>
- <td>
- <h1 align="center">"Quoted"
- I/O Manipulators<br>
- for Strings</h1>
- </td>
- </tr>
- </tbody>
- </table>
- <table border="1" cellpadding="5" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td>
- <p align="center"><b>"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></b></td>
- </tr>
- </table>
- <h2>Introduction</h2>
- <p>C++ Standard library stream I/O for strings that contain embedded spaces
- can produce unexpected results. For example,</p>
- <blockquote>
- <pre>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</pre>
- </blockquote>
- <p>The Boost <code>quoted</code> stream I/O manipulator places delimiters, defaulted
- to the double-quote (<code>"</code>), around strings on output, and strips off
- the delimiters on input. This ensures strings with embedded spaces round-trip as
- desired. For example,</p>
- <blockquote>
- <pre>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</pre>
- </blockquote>
- <p>If the string contains the delimiter character, on output that character will
- be preceded by an escape character, as will the escape character itself:</p>
- <blockquote>
- <pre>std::cout << quoted("'Jack & Jill'", '&', '\''); // outputs: '&'Jack && Jill&''</pre>
- </blockquote>
- <h2>Header <a href="../../../boost/io/detail/quoted_manip.hpp"><boost/io/quoted_manip.hpp></a> synopsis</h2>
- <pre>namespace boost
- {
- namespace io
- {
- // manipulator for const std::basic_string&
- template <class Char, class Traits, class Alloc>
- <b><i>unspecified-type1</i></b> quoted(const std::basic_string<Char, Traits, Alloc>& string,
- Char escape='\\', Char delim='\"');
- // manipulator for const C-string*
- template <class Char>
- <b><i>unspecified-type2</i></b> quoted(const Char* string,
- Char escape='\\', Char delim='\"');
- // manipulator for non-const std::basic_string&
- template <class Char, class Traits, class Alloc>
- <b><i>unspecified-type3</i></b> quoted(std::basic_string<Char, Traits, Alloc>& string,
- Char escape='\\', Char delim='\"');
- }
- }</pre>
- <p><i><b><code>unspecified_type1</code></b></i>, <i><b><code>unspecified_type2</code></b></i>,
- and <i><b><code>unspecified_type3</code></b></i> are implementation supplied
- types with implementation supplied <code>operator<<</code>:</p>
- <blockquote>
- <pre>template <class Char, class Traits>
- std::basic_ostream<Char, Traits>&
- operator<<(std::basic_ostream<Char, Traits>& os, const <i><b><code>unspecified_typeN</code></b></i>& proxy);</pre>
- <p><i>Effects:</i> Inserts characters into <code>os</code>:</p>
- <ul>
- <li><code>delim</code>.</li>
- <li>Each character in <code>string</code>. If the character to be output is
- equal to <code>escape</code> or <code>delim</code>, as determined by <code>
- operator==</code>, first output <code>escape</code>. </li>
- <li><code>delim</code>.</li>
- </ul>
- <p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code>
- have the type and value of the corresponding arguments of the call to the <code>
- quoted</code> function that constructed <code>proxy</code>.</p>
- <p><i>Returns:</i> <code>os</code>. </p>
- </blockquote>
- <p><i><b><code>unspecified_type3</code></b></i> is an implementation supplied
- type with an implementation supplied <code>operator>></code>:</p>
- <blockquote>
- <pre>template <class Char, class Traits>
- std::basic_istream<Char, Traits>&
- operator>>(std::basic_istream<Char, Traits>& is, const <i><b><code>unspecified_type3</code></b></i>& proxy);</pre>
- <p><i>Effects:</i> Extracts characters from <code>os</code>:</p>
- <ul>
- <li>If the first character extracted is equal to delim, as determined by
- <code>operator==</code>, then:<ul>
- <li>Turn off the <code>skipws</code> flag.</li>
- <li><code>string.clear()</code></li>
- <li>Until an unescaped <code>delim</code> character is reached or <code>
- is.not_good()</code>, extract
- characters from <code>os</code> and append them to <code>string</code>,
- except that if an <code>escape</code> is reached, ignore it and append the
- next character to <code>string</code>.</li>
- <li>Discard the final <code>delim</code> character.</li>
- <li>Restore the <code>skipws</code> flag to its original value.</li>
- </ul>
- </li>
- <li>Otherwise, <code>os >> string</code>.</li>
- </ul>
- <p><i>Remarks:</i> <code>string</code>, <code>escape</code>, and <code>delim</code>
- have the type and value of the corresponding arguments of the call to the <code>
- quoted</code> function that constructed <code>proxy</code>.</p>
- <p><i>Returns:</i> <code>is</code>. </p>
- </blockquote>
- <h2>Acknowledgements</h2>
- <p>The <code>quoted()</code> 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. </p>
- <hr>
- <p>© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010</p>
- <p>Distributed under the Boost Software License, Version 1.0. See
- <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
- <p>Revised
- <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->08 March 2013<!--webbot bot="Timestamp" endspan i-checksum="27284" --></p>
- </body>
- </html>
|