<?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>&quot;quoted&quot; proposal</title>
  <meta name="generator" content="Microsoft FrontPage 5.0" />
<style type="text/css">
body  {
        font-family: sans-serif;
        margin: 1em;
        max-width : 7.5in;
      }

table { margin: 0.5em; }

pre   { background-color:#D7EEFF }

ins   { background-color:#CCFFCC }
del   { background-color:#FFCACA }

  </style>
</head>

<body>

  <table border="0" style="border-collapse: collapse" bordercolor="#111111" cellpadding="0" cellspacing="0">
    <tr>
      <td height="23">Document number:&nbsp;&nbsp; </td>
      <td height="23"><span style="background-color: #FFFF00">N3654</span></td>
    </tr>
    <tr>
      <td height="23">Date:</td>
      <td height="23">
      <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2013-04-19<!--webbot bot="Timestamp" endspan i-checksum="12255" --></td>
    </tr>
    <tr>
      <td height="23">Project:</td>
      <td height="23">Programming Language C++</td>
    </tr>
    <tr>
      <td valign="top" height="22">Reply-to:</td>
      <td height="22">Beman Dawes &lt;bdawes at acm dot org&gt;</td>
    </tr>
  </table>


<h1>Quoted Strings Library Proposal (Revision 2)</h1>


<h2><a name="Introduction">Introduction</a></h2>


<p>Character strings enclosed in quotation marks are an element of numerous common data formats (e.g. 
XML, CSV), yet C++ standard library stream I/O offers no direct support. 
Furthermore, standard library stream I/O has 
a problem with embedded spaces in strings that can trip the unwary. The proposed solution provides 
direct support for quoted strings, avoids embedded spaces problems and is more 
efficient than likely user provided solutions.</p>


<p>The proposal is suitable for either C++1y or a standard library Technical Specification 
(TS). It 
is a pure addition that will 
break no existing standard-conforming user code. It is based on 
a <a href="http://www.boost.org/libs/io/doc/quoted_manip.html">Boost component</a> that has been shipping for several years. The declarations 
for the proposed functions can go in a new header or 
an existing header.</p>


<p>The proposed wording below assumes the target is C++1y and places the 
function declarations in &lt;iomanip&gt;.</p>


<h2><a name="Problem">Problem</a> description</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 = &quot;foolish me&quot;;
std::string round_trip;

ss &lt;&lt; original;
ss &gt;&gt; round_trip;

std::cout &lt;&lt; original;   // outputs: foolish me
std::cout &lt;&lt; round_trip; // outputs: foolish

assert(original == round_trip); // assert will fire</pre>
</blockquote>
<p>The proposed <code>quoted</code> stream I/O manipulator places delimiters, defaulted 
to 
double-quote (<code>&quot;</code>), around strings on output, and strips off 
the delimiters on input. This ensures strings with embedded white space round-trip as 
desired. For example,</p>
<blockquote>
  <pre>std::stringstream ss;
std::string original = &quot;foolish me&quot;;
std::string round_trip;

ss &lt;&lt; quoted(original);
ss &gt;&gt; quoted(round_trip);

std::cout &lt;&lt; original;     // outputs: foolish me
std::cout &lt;&lt; round_trip;   // outputs: foolish me

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, default to backslash (<code>\</code>), as will the escape character itself:</p>
<blockquote>
  <pre>std::cout &lt;&lt; quoted(&quot;She said \&quot;Hi!\&quot;&quot;);  // outputs: &quot;She said \&quot;Hi!\&quot;&quot;</pre>
</blockquote>


<h2><a name="Revision-history">Revision history</a></h2>


<p><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3654.html">
N3654</a> - Revision 2 
(post-Bristol mailing)</p>


  <ul>
    <li>Swap order of <code>const basic_string&amp;</code> and <code>const char*</code> 
    quoted functions in synopsis per Bristol LWG.</li>
    <li>Change <code>charT delim='&quot;'</code> to <code>charT delim=charT('&quot;')</code> 
    per Bristol LWG.</li>
    <li>Ditto for <code>escape</code>. This wasn't asked for, but seems 
    inconsistent to change for <code>delim</code> without also changing for
    <code>escape</code>.</li>
    <li>Strike unnecessary verbiage from Returns per Bristol LWG.</li>
    <li dir="ltr">
    <p dir="ltr">Removed unneeded template parameters <code>traits</code> and
    <code>Allocator</code> from the <code>const char*</code> signature per 
    Bristol LWG.</li>
    <li>Strike incorrect <code>const</code> from extractor signature per Bristol 
    LWG.</li>
    <li>
    <p dir="ltr">In two <i>Returns:</i>, clarify as indicated below that the 
    stream's <code>char_type</code> and the <code>charT</code> template 
    parameter must be the same type, as requested by the Bristol LWG.</li>
    <li>
    <p dir="ltr">No change has been made in response the Bristol LWG query 
    &quot;should the operator== actually be the eq from some character traits?&quot; It 
    seems harmless and very clear to leave the operator== spec wording 
    unchanged. But the LWG has the most expertise to answer the question; I'll 
    defer to them if they want a change.</li>
    <li>
    <p dir="ltr">Remove unnecessary <code>std::</code> in several places. 
    (Daniel
    <span email="daniel.kruegler@gmail.com" name="Daniel Krgler" class="gD">
    Krgler)</span></li>
    <li>
    <p dir="ltr"><span class="gD">Add &quot;member type&quot; in two places for improved 
    clarity. </span>(Daniel
    <span email="daniel.kruegler@gmail.com" name="Daniel Krgler" class="gD">
    Krgler)</span></li>
    <li>
    <p dir="ltr"><span class="gD">Revert a clarity &quot;fix&quot; and add comment in two 
    places indicating the awkward wording comes from the current working paper. 
    (</span>Daniel
    <span email="daniel.kruegler@gmail.com" name="Daniel Krgler" class="gD">
    Krgler)</span></li>
    <li>
    <p dir="ltr"><span class="gD">Fix the spec for missing case of insertion via 
    the T13 overload. (Nice catch from Alisdair Meredith)</span></li>
    <li>
    <p dir="ltr"><span class="gD">Fix </span><code>!in</code><span class="gD"> 
    and </span><code>in &gt;&gt; s</code><span class="gD"> typos. (Jonathan Wakely)</span></li>
  </ul>


<p><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3570.html">
N3570</a> - Revision 1 
(pre-Bristol mailing)</p>
  <ul>
    <li>Remove unnecessary backslash from character literals in default arguments.</li>
    <li>Rewrite the proposed wording to follow the standard library's form for 
    iomanip functions. Note that this has the effect of making error handling 
    well-specified, as requested by the LWG at the Portland meeting.</li>
    <li>Editorial cleanup.</li>
  </ul>


  <p>
  <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3431.html">
  N3431</a> Initial paper (pre-Portland mailing)</p>
<h2><a name="Proposed-wording">Proposed wording</a></h2>
<p><span style="background-color: #DBDBDB"><i>Gray shaded italic text is 
commentary, and not to be added to the working paper</i>.</span></p>
<p><i><span style="background-color: #DBDBDB">Change 27.7.1 Overview [iostream.format.overview], &quot;Header &lt;iomanip&gt; 
synopsis&quot; as indicated:</span></i></p>
  <blockquote>
    <pre>namespace std {
// <i>types</i> T1, T2, ... <i>are unspecified implementation types</i>
<i>T1</i> resetiosflags(ios_base::fmtflags mask);
<i>T2</i> setiosflags (ios_base::fmtflags mask);
<i>T3</i> setbase(int base);
template&lt;charT&gt; <i>T4</i> setfill(charT c);
<i>T5</i> setprecision(int n);
<i>T6</i> setw(int n);
template &lt;class moneyT&gt; <i>T7</i> get_money(moneyT&amp; mon, bool intl = false);
template &lt;class moneyT&gt; <i>T8</i> put_money(const moneyT&amp; mon, bool intl = false);
template &lt;class charT&gt; <i>T9</i> get_time(struct tm* tmb, const charT* fmt);
template &lt;class charT&gt; <i>T10</i> put_time(const struct tm* tmb, const charT* fmt);

<ins>template &lt;class charT&gt;</ins>
  <ins><i>T11</i> quoted(const charT* s, charT delim=charT('&quot;'), charT escape=charT('\\'));</ins>

<ins>template &lt;class charT, class traits, class Allocator&gt;</ins>
  <ins><i>T12</i> quoted(const basic_string&lt;charT, traits, Allocator&gt;&amp; s,</ins>
             <ins>charT delim=charT('&quot;'), charT escape=charT('\\'));</ins>

<ins>template &lt;class charT, class traits, class Allocator&gt;</ins>
  <ins><i>T13</i> quoted(basic_string&lt;charT, traits, Allocator&gt;&amp; s,</ins>
             <ins>charT delim=charT('&quot;'), charT escape=charT('\\'));</ins>
}</pre>
  </blockquote>
<p><i><span style="background-color: #DBDBDB">After 27.7.5 Extended manipulators [ext.manip], add a new sub-section:</span></i></p>
  <blockquote>
<p>27.7.6 Quoted manipulators [quoted.manip]</p>
<p>[<i>Note</i>: Quoted manipulators provide string insertion and extraction of 
quoted strings (for example, XML and CSV formats). Quoted manipulators are useful in ensuring 
that the content of a string with embedded spaces remains unchanged if inserted and then extracted 
via stream I/O.
<i>--end note</i>]</p>
    <pre>template &lt;class charT&gt;
<i>  unspecified</i> quoted(const charT* s, charT delim=charT('&quot;'), charT escape=charT('\\'));
template &lt;class charT, class traits, class Allocator&gt;
<i>  unspecified</i> quoted(const basic_string&lt;charT, traits, Allocator&gt;&amp; s,
                   charT delim=charT('&quot;'), charT escape=charT('\\'));</pre>
    <blockquote>
<p><i>Returns:</i> An object of unspecified type such that if <code>out</code> 
is an instance of <code>basic_ostream</code> <ins>with member type <code>char_type</code> the same as
<code>charT</code>,</ins><code> <del>&lt;charT, traits&gt;, </del></code> <del><code>s</code> is an instance of a type convertible to<code> basic_string&lt;charT, traits, Allocator&gt;</code>, 
or <code>const char*</code>, respectively, and
<code>delim</code> and <code>escape</code> are instances of
<code>charT</code>,</del> then the expression <code>out &lt;&lt; quoted(s, delim, escape)</code> 
behaves as if it inserts the following characters into <code>out</code> using character inserter function templates ([ostream.inserters.character]), 
which may throw <code>ios_base::failure</code> ([ios::failure]):</p>
  <ul>
    <li><code>delim</code>.</li>
    <li>Each character in <code>s</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>The expression <code>out &lt;&lt; quoted(s, delim, escape)</code> shall have type <code>basic_ostream&lt;charT, traits&gt;&amp;</code> and value <code>out</code>.
<span style="font-style: italic; background-color: #DBDBDB">This wording is the 
form for such statements in the current wording paper [std.manip].</span></p>
    </blockquote>
    <pre>template &lt;class charT, class traits, class Allocator&gt;
<i>  unspecified</i> quoted(basic_string&lt;charT, traits, Allocator&gt;&amp; s,
                   charT delim=charT('&quot;'), charT escape=charT('\\'));
</pre>
    <blockquote>
<p><i>Returns:</i> An object of unspecified type such that:</p>
  <ul>
    <li>If <code>in</code> 
is an instance of <code>basic_istream</code> <ins>with member type <code>char_type</code> the same as
<code>charT</code></ins><code>&nbsp; <del>&lt;charT,
traits&gt;</del></code><del>, <code>s</code> is an instance of <code>basic_string&lt;charT, traits, Allocator&gt;</code>, 
and
<code>delim</code> and <code>escape</code> are instances of types
<code>charT</code></del>, then the expression <code>in &gt;&gt; quoted(s, delim, escape)</code> 
behaves as if it extracts the following characters from <code>in</code> 
using basic_istream::operator&gt;&gt; ([istream::extractors]) 
which may throw <code>ios_base::failure</code> ([ios::failure]):<br>
&nbsp;<ul>
      <li>If the first character extracted is equal to <code>delim</code>, as determined by
    <code>operator==</code>, then:<ul>
      <li>Turn off the <code>skipws</code> flag.</li>
      <li><code>s.clear()</code></li>
      <li dir="ltr">
      <p dir="ltr">Until an unescaped <code>delim</code> character is reached or <code>
      !in</code>, extract 
      characters from <code>in</code> and append them to <code>s</code>, 
      except that if an <code>escape</code> is reached, ignore it and append the 
      next character to <code>s</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>in &gt;&gt; s</code>.<br>
&nbsp;</li>
    </ul>
    </li>
    <li><ins><span style="background-color: #FFFF00">If <code>out</code> 
is an instance of <code>basic_ostream</code> with member type <code>char_type</code> the same as
<code>charT</code>, then the expression <code>out &lt;&lt; quoted(s, delim, escape)</code> 
    behaves as specified for the <code>const basic_string&lt;charT, traits, Allocator&gt;&amp;</code> 
    overload of the <code>quoted</code> function.</span></ins></li>
</ul>
<p>The expression <code>in &gt;&gt; quoted(s, delim, escape)</code> shall have type
<code>basic_istream&lt;charT, traits&gt;&amp;</code> and value <code>in</code>.<span style="background-color: #FFFF00">
</span>
<ins><span style="background-color: #FFFF00">The expression <code>out &lt;&lt; quoted(s, delim, escape)</code> shall have type
<code>basic_ostream&lt;charT, traits&gt;&amp;</code> and value <code>out</code>.</span></ins><span style="background-color: #FFFF00">
</span>
<span style="font-style: italic; background-color: #DBDBDB">This wording is the 
form for such statements in the current wording paper [std.manip].</span></p>
    </blockquote>
  </blockquote>
  <h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>The <code>quoted()</code> stream manipulators 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. Thanks to the LWG in Portland and Bristol for additional 
improvements.</p>
<hr>

</body>
</html>
