164 lines
7.0 KiB
HTML
164 lines
7.0 KiB
HTML
<?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><EFBFBD> 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> |