<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Generic to_string/to_wstring functions</title>
    <style>
        ins { background-color: LightGreen; }
        del { background-color: LightPink; }
        pre { font: inherit; margin: 1em 3em; }
        h1 { counter-reset: h2; }
        h2:before { counter-increment: h2; content: counter(h2, upper-roman) ". "; }
        nav ol { list-style-type: upper-roman; }
    </style>
</head>
<body>

    <table><tbody>
        <tr><td>Document number:</td><td>P0117R0</td></tr>
        <tr><td>Date:</td><td>2015-09-25</td></tr>
        <tr><td>Project:</td><td>Programming Language C++, Library Evolution Working Group</td></tr>
        <tr><td>Reply-to:</td><td>Robert Kawulak &lt;Robert Kawulak at gmail dot com&gt;</td></tr>
    </tbody></table>

    <h1>Generic <code>to_string</code>/<code>to_wstring</code> functions</h1>

    <nav><h2 id="contents">Table of Contents</h2>
        <ol start="2">
            <li><a href="#introduction">Introduction</a></li>
            <li><a href="#motivation">Motivation</a></li>
            <li><a href="#impact">Impact on the Standard</a></li>
            <li><a href="#design">Design Decisions</a></li>
            <li><a href="#specifications">Technical Specifications</a></li>
        </ol>
    </nav>

    <section><h2 id="introduction">Introduction</h2>

The paper proposes extending the Standard Library with function templates equivalent to the following:

<pre><code>template&lt;class Ch, class Tr = char_traits&lt;Ch&gt;, class Alloc = allocator&lt;Ch&gt;, class... Args&gt;
basic_string&lt;Ch,Tr,Alloc&gt; to_basic_string(Args&amp;&amp;... args)
{
    basic_ostringstream&lt;Ch,Tr,Alloc&gt; stream;
    stream.exceptions(ios_base::failbit | ios_base::badbit);
    stream &lt;&lt; ... &lt;&lt; forward&lt;Args&gt;(args);
    return stream.str();
}

template&lt;class... Args&gt;
string to_string(Args&amp;&amp;... args)
{
    return to_basic_string&lt;char&gt;(forward&lt;Args&gt;(args)...);
}

template&lt;class... Args&gt;
wstring to_wstring(Args&amp;&amp;... args)
{
    return to_basic_string&lt;wchar_t&gt;(forward&lt;Args&gt;(args)...);
}
</code></pre>

    </section>

    <section><h2 id="motivation">Motivation</h2>

<p>For a long time C++ programmers have been looking for an easy way to convert an object into its string representation. A typical answer to this problem was to create a local <code>ostringstream</code>, insert the object into the stream, and then obtain the resulting string with the <code>str</code> member function. This solution is simple, safe, flexible and extensible, though definitely too verbose for something that rather ought to be a single function call. C++11 provided (a partial) solution in the form of a set of overloaded <code>to_string</code>/<code>to_wstring</code> functions. Unfortunately, these are limited only to the built-in numeric types. Non-standard solutions exist too – most notably <code>boost::lexical_cast</code>, which offers two-way conversion of objects and strings, but lacks any formatting control.</p>

<p>This paper proposes a solution that:
<ul>
<li>generalizes the existing <code>to_string</code>/<code>to_wstring</code> functions for any type that provides a stream output operator and for <a href="#basic_string_spec">any <code>basic_string</code> specialisation</a>,</li>
<li>remains consistent and <a href="#impact">mostly compatible</a> with these functions,</li>
<li>provides <a href="#capabilities">extra formatting and concatenation capabilities</a>,</li>
<li>is conceptually simple by building upon the familiar <code>ostringstream</code> solution.</li>
</ul></p>

        <section><h3 id="capabilities">Formatting capabilities</h3>

One notable feature of the proposed solution is that it is a variadic function template. This doesn't make the interface or the implementation much more complicated, yet it provides some benefits in terms of flexibility and efficiency. First, this allows for providing of additional formatting instructions using the familiar stream manipulators:

<pre><code>int byte = 255;
to_string(hex, uppercase, byte); // format as an uppercase hexadecimal number: "FF"
</code></pre>

Second, it allows for concise and possibly more efficient concatenation of several objects' representations into a single string:

<pre><code>int major = 4, minor = 11, revision = 2;
to_string(major, '.', minor, '.', revision); // yields "4.11.2"
</code></pre>

An example combining the two use cases shows how this simple solution is at the same time quite powerful:

<pre><code>int hours = 4, minutes = 9; bool afternoon = true;
to_string(hours, ':', setfill('0'), setw(2), minutes, afternoon ? " PM" : " AM"); // "4:09 PM"
</code></pre>

There is yet another use case of the proposed solution: it allows to temporarily reset all formatting flags to the defaults when using an output stream. This may be useful to ensure certain formatting for selected output operations without having to set and then reset all possibly relevant formatting flags. It also allows to treat a subset of output operations as an atomic part, managed by some formatting flags as a whole. Consider:

<pre><code>cout &lt;&lt; right &lt;&lt; setfill('_') &lt;&lt; setw(8) &lt;&lt;
    to_string(hours, ':', setfill('0'), setw(2), minutes); // "____4:09"
</code></pre>

The <code>right</code>, <code>setfill('_')</code> and <code>setw(8)</code> directives don't affect formatting of elements of <code>"4:09"</code> substring, but rather of the substring as a whole. Also, the <code>setfill('0')</code> and <code>setw(2)</code> directives have no effect outside of the substring generation.

        </section>

        <section><h3 id="basic_string_spec">Support for any <code>basic_string</code> specialisation</h3>

Proposed <code>to_string</code> and <code>to_wstring</code> function templates delegate the real work to a more generic <code>to_basic_string</code> function template. Calling the latter directly allows for customisation of the character type, traits and allocator used by the employed stream and the resulting string beyond the two default configurations provided by <code>to_string</code> and <code>to_wstring</code>.

        </section>

    </section>

    <section><h2 id="impact">Impact on the Standard</h2>

In principle, proposed function templates' specialisations for built-in numeric types yield results consistent with the already existing <code>to_string</code>/<code>to_wstring</code> overloads. The old and new functions could coexist, relying on the overload resolution to prefer a non-templated (existing) version in case of a matching argument type. However, a compatibility problem may arise in case of some distinct but implicitly convertible argument types:

<pre><code>to_string(0);     // before: calls to_string(int), now: calls to_string(int)
to_string(false); // before: calls to_string(int), now: calls to_string&lt;bool&gt;(bool&amp;&amp;)
to_string('0');   // before: calls to_string(int), now: calls to_string&lt;char&gt;(char&amp;&amp;)
</code></pre>

While the effect is identical in the first two cases (the result is always <code>"0"</code>), in the last one the result will change from <code>"48"</code> (assuming ASCII encoding) to <code>"0"</code>. There are several ways to deal with problematic specialisation cases like this one:

<ul>
<li>rename the proposed function templates, e.g. to <code>to_str</code>/<code>to_wstr</code>, <code>format</code>/<code>wformat</code> or <code>stringize</code>/<code>wstringize</code>,</li>
<li>add the remaining overloads of <code>to_string</code>/<code>to_wstring</code> functions supporting the existing behaviour, e.g.
<pre><code>string to_string(char c) { return to_string(static_cast&lt;int&gt;(c)); }</code></pre>
– the templated version call can still be forced with the syntax: <code>to_string&lt;&gt;('0')</code>,</li>
<li>explicitly specify the behaviour of new functions as always falling back to the existing ones in case of implicitly convertible argument types,</li>
<li>ignore the problem for the sake of consistency with I/O Streams behaviour (possibly even deprecating the existing functions in favour of the templated ones).</li>
</ul>

The paper currently reflects the last option (excluding deprecation), but the author is aware of the significance of backwards compatibility and seeks guidance from the Committee members regarding their preferred solution.

    </section>

    <section><h2 id="design">Design Decisions</h2>

        <section><h3 id="empty_args">Empty argument list case</h3>

There is a question whether calls with empty argument list (i.e. <code>to_string()</code>), yielding an empty string, should be explicitly disallowed. The author's opinion is no – this specialisation, even if lacking obvious use cases, is consistent with the general concept and there are no obvious disadvantages to keeping it. Also, providing such a somewhat artificial limitation could be potentially disruptive in generic code.

        </section>

        <section><h3 id="error_handling">Error handling</h3>

The functions set the exception flags (which are not set by default) on the stream object in order to detect and signal any potential errors encountered during the formatting operation rather than silently ignore them.

        </section>

        <section><h3 id="performance">Performance</h3>

Known issue of the <code>ostringstream</code> solution used under the hood by the proposed function templates is its relatively poor performance. However, in accordance with the “as if” rule, implementations are free to provide (and probably would benefit a lot from) optimisations for specific argument types, e.g. using <code>sprintf</code> directly just like the existing <code>to_string</code>/<code>to_wstring</code> functions or to preallocating the string's storage if maximum length of all the arguments can be determined upfront.

        </section>

    </section>

    <section><h2 id="specifications">Technical Specifications</h2>

Proposed wording will be provided in a future revision of the document.

    </section>

</body>
</html>
