<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">
<title>Text Formatting</title>

<style type="text/css">

body { color: #000000; background-color: #FFFFFF; }
del { text-decoration: line-through; color: #8B0040; }
ins { text-decoration: underline; color: #005100; }

p.example { margin-left: 2em; }
pre.example { margin-left: 2em; }
div.example { margin-left: 2em; }

code.extract { background-color: #F5F6A2; }
pre.extract { margin-left: 2em; background-color: #F5F6A2;
  border: 1px solid #E1E28E; }

p.function { }
.attribute { margin-left: 2em; }
.attribute dt { float: left; font-style: italic;
  padding-right: 1ex; }
.attribute dd { margin-left: 0em; }

blockquote.std { color: #000000; background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stddel { text-decoration: line-through;
  color: #000000; background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding-left: 0.5empadding-right: 0.5em; ; }

blockquote.stdins { text-decoration: underline;
  color: #000000; background-color: #C8FFC8;
  border: 1px solid #B3EBB3; padding: 0.5em; }

table { border: 1px solid black; border-spacing: 0px;
  margin-left: auto; margin-right: auto; }
th { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }
td { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }

.content {
  max-width: 800px;
  margin-left: auto;
  margin-right: auto;
}

</style>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"
        type="text/javascript"> </script>

<script type="text/javascript">$(function() {
    var next_id = 0
    function find_id(node) {
        // Look down the first children of 'node' until we find one
        // with an id. If we don't find one, give 'node' an id and
        // return that.
        var cur = node[0];
        while (cur) {
            if (cur.id) return curid;
            if (cur.tagName == 'A' && cur.name)
                return cur.name;
            cur = cur.firstChild;
        };
        // No id.
        node.attr('id', 'gensection-' + next_id++);
        return node.attr('id');
    };

    // Put a table of contents in the #toc nav.

    // This is a list of <ol> elements, where toc[N] is the list for
    // the current sequence of <h(N+2)> tags. When a header of an
    // existing level is encountered, all higher levels are popped,
    // and an <li> is appended to the level
    var toc = [$("<ol/>")];
    $(':header').not('h1').each(function() {
        var header = $(this);
        // For each <hN> tag, add a link to the toc at the appropriate
        // level.  When toc is one element too short, start a new list
        var levels = {H2: 0, H3: 1, H4: 2, H5: 3, H6: 4};
        var level = levels[this.tagName];
        if (typeof level == 'undefined') {
            throw 'Unexpected tag: ' + this.tagName;
        }
        // Truncate to the new level.
        toc.splice(level + 1, toc.length);
        if (toc.length < level) {
            // Omit TOC entries for skipped header levels.
            return;
        }
        if (toc.length == level) {
            // Add a <ol> to the previous level's last <li> and push
            // it into the array.
            var ol = $('<ol/>')
            toc[toc.length - 1].children().last().append(ol);
            toc.push(ol);
        }
        var header_text = header.text();
        toc[toc.length - 1].append(
            $('<li/>').append($('<a href="#' + find_id(header) + '"/>')
                              .text(header_text)));
    });
    $('#toc').append(toc[0]);
})
</script>

</head>
<body>

<address align=right>
Document number: P0645R0<br>
Audience: Library Evolution<br>
<br>
<a href="mailto:victor.zverovich@gmail.com">Victor Zverovich</a><br>
<a href="mailto:lwh@fb.com">Lee Howes</a><br>
2017-05-22
</address>
<hr>

<div class="content">
<h1>Text Formatting</h1>

<div id="toc"></div>

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

<p>
Even with proliferation of graphical and voice user interfaces, text remains one
of the main ways for humans to interact with computer programs and programming
languages provide a variety of methods to perform text formatting.
The first thing we do when learning a new programming language is often writing
a &quot;Hello, World!&quot; program that performs simple formatted output.
</p>

<p>
C++ has not one but two standard APIs for doing formatted output, the
<code>printf</code> family of functions inherited from C and the I/O streams
library (iostreams).
While iostreams are usually the recommended way of doing formatted
output in C++ for safety and extensibility reasons, <code>printf</code> offers
some advantages, such as arguably more natural function call API, separation of
formatted message and arguments, possibly with argument reordering as a POSIX
extension, and often more compact code, both source and binary.
</p>

<p>
This paper proposes a new text formatting library that can be used as a
safe and extensible alternative to the <code>printf</code> family of functions.
It is intended to complement the existing C++ I/O streams library and reuse
some of its infrastructure such as overloaded insertion operators for
user-defined types.
</p>

<p>
Example:

<pre class="example">
<code>string message = fmt::format("The answer is {}.", 42);</code>
</pre>
</p>

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

<h3><a name="Syntax">Format string syntax</a></h3>

<p>
Variations of the printf format string syntax are arguably the most popular
among the programming languages and C++ itself inherits <code>printf</code>
from C <a href="#1">[1]</a>. The advantage of the printf syntax is that many
programmers are familiar with it. However, in its current form it has a number
of issues:
</p>

<ul>
<li>Many format specifiers like <code>hh</code>, <code>h</code>, <code>l</code>,
    <code>j</code>, etc. are used only to convey type information.
    They are redundant in type-safe formatting and would unnecessarily
    complicate specification and parsing.</li>
<li>There is no standard way to extend the syntax for user-defined types.</li>
<li>There are subtle differences between different implementations. For example,
    POSIX positional arguments <a href="#2">[2]</a> are not supported on
    some systems <a href="#6">[6]</a>.</li>
<li>Using <code>'%'</code> in a custom format specifier, e.g. for
    <code>put_time</code>-like time formatting, poses difficulties.</li>
</ul>

<p>
Although it is possible to address these issues while maintaining resemblance
to the original printf format, this will still break compatibility and can
potentially be more confusing to users than introducing a different syntax.
</p>

<p>
Therefore we propose a new syntax based on the ones used in Python
<a href="#3">[3]</a>, the .NET family of languages <a href="#4">[4]</a>,
and Rust <a href="#5">[5]</a>. This syntax employs <code>'{'</code> and
<code>'}'</code> as replacement field delimiters instead of <code>'%'</code>
and it is described in details in the <a href="#SyntaxRef">syntax reference</a>.
Here are some of the advantages:
</p>

<ul>
<li>Consistent and easy to parse mini-language focused on formatting rather
    than conveying type information</li>
<li>Extensibility and support for custom format strings for user-defined
    types</li>
<li>Positional arguments</li>
<li>Support for both locale-specific and locale-independent formatting (see
    <a href="#Locale">Locale support</a>)</li>
<li>Formatting improvements such as better alignment control, fill character,
    and binary format
</ul>

<p>
The syntax is expressive enough to enable translation, possibly automated,
of most printf format strings. The correspondence between <code>printf</code>
and the new syntax is given in the following table.
</p>

<table>
<thead>
<tr><th>printf</th><th>new</th></tr>
</thead>
<tbody>
<tr><td>-</td><td>&lt;</td></tr>
<tr><td>+</td><td>+</td></tr>
<tr><td><em>space</em></td><td><em>space</em></td></tr>
<tr><td>#</td><td>#</td></tr>
<tr><td>0</td><td>0</td></tr>
<tr><td>hh</td><td>unused</td></tr>
<tr><td>h</td><td>unused</td></tr>
<tr><td>l</td><td>unused</td></tr>
<tr><td>ll</td><td>unused</td></tr>
<tr><td>j</td><td>unused</td></tr>
<tr><td>z</td><td>unused</td></tr>
<tr><td>t</td><td>unused</td></tr>
<tr><td>L</td><td>unused</td></tr>
<tr><td>c</td><td>c (optional)</td></tr>
<tr><td>s</td><td>s (optional)</td></tr>
<tr><td>d</td><td>d (optional)</td></tr>
<tr><td>i</td><td>d (optional)</td></tr>
<tr><td>o</td><td>o</td></tr>
<tr><td>x</td><td>x</td></tr>
<tr><td>X</td><td>X</td></tr>
<tr><td>u</td><td>d (optional)</td></tr>
<tr><td>f</td><td>f</td></tr>
<tr><td>F</td><td>F</td></tr>
<tr><td>e</td><td>e</td></tr>
<tr><td>E</td><td>E</td></tr>
<tr><td>a</td><td>a</td></tr>
<tr><td>A</td><td>A</td></tr>
<tr><td>g</td><td>g (optional)</td></tr>
<tr><td>G</td><td>G</td></tr>
<tr><td>n</td><td>unused</td></tr>
<tr><td>p</td><td>p (optional)</td></tr>
</tbody>
</table>

<p>
Width and precision are represented similarly in <code>printf</code> and the
proposed syntax with the only difference that runtime value is specified by
<code>*</code> in the former and <code>{}</code> in the latter, possibly with
the index of the argument inside the braces.
</p>

<p>
As can be seen from the table above, most of the specifiers remain the same
which simplifies migration from <code>printf</code>. Notable difference is
in the alignment specification. The proposed syntax allows left, center,
and right alignment represented by <code>'&lt;'</code>, <code>'^'</code>,
and <code>'&gt;'</code> respectively which is more expressive than the
corresponding <code>printf</code> syntax. The latter only supports left and
right (the default) alignment.
</p>

<p>
The following example uses center alignment and <code>'*'</code> as a fill
character:
</p>

<pre class="example">
<code>fmt::format("{:*^30}", "centered");</code>
</pre>

<p>
resulting in <code>"***********centered***********"</code>.
The same formatting cannot be easily achieved with <code>printf</code>.
</p>

<h3><a name="Extensibility">Extensibility</a></h3>

<p>
Both the format string syntax and the API are designed with extensibility in
mind. The mini-language can be extended for user-defined types and users can
provide functions that do parsing and formatting for such types.
</p>

<p>The general syntax of a replacement field in a format string is

<pre>
<code>replacement-field ::= '{' [arg-id] [':' format-spec] '}'</code>
</pre>

<p>
where <code>format-spec</code> is predefined for built-in types, but can be
customized for user-defined types. For example, the syntax can be extended
for <code>put_time</code>-like date and time formatting
</p>

<pre class="example">
<code>time_t t = time(nullptr);
string date = fmt::format("The date is {0:%Y-%m-%d}.", *localtime(&amp;t));</code>
</pre>

<p>by providing an overload of <code>format_value</code> for
<code>tm</code>:</p>

<pre class="example">
<code>void format_value(fmt::buffer&amp; buf, const tm&amp; tm, fmt::context&amp; ctx);</code>
</pre>

<p>
The <code>format_value</code> function parses the portion of the format
string corresponding to the current argument and formats the value into
<code>buf</code> using <code>format_to</code> or the buffer API.</p>

<p>
The default implementation of <code>format_value</code> calls ostream insertion
<code>operator&lt;&lt;</code> if available.
</p>

<h3><a name="Safety">Safety</a></h3>

<p>
Formatting functions rely on variadic templates instead of the mechanism
provided by <code>&lt;cstdarg&gt;</code>. The type information is captured
automatically and passed to formatters guaranteeing type safety and making
many of the <code>printf</code> specifiers redundant (see <a href="#Syntax">
Format String Syntax</a>). Buffer management is automatic to prevent
buffer overflow errors common to <code>printf</code>.
</p>

<h3><a name="Locale">Locale support</a></h3>

<p>
As pointed out in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0067r1.html">
P0067R1: Elementary string conversions</a> there is a number of use
cases that do not require internationalization support, but do require high
throughput when produced by a server. These include various text-based
interchange formats such as JSON or XML. The need for locale-independent
functions for conversions between integers and strings and between
floating-point numbers and strings has also been highlighted in
<a href="http://open-std.org/JTC1/SC22/WG21/docs/papers/2015/n4412.html">
N4412: Shortcomings of iostreams</a>. Therefore a user should be able to
easily control whether to use locales or not during formatting.
</p>

<p>
We follow Python's approach <a href="#3">[3]</a> and designate a separate format
specifier <code>'n'</code> for locale-aware numeric formatting. It applies to
all integral and floating-point types. All other specifiers produce output
unaffected by locale settings. This can also have positive effect on performance
because locale-independent formatting can be implemented more efficiently.
</p>

<h3><a name="PosArguments">Positional arguments</a></h3>

<p>
An important feature for localization is the ability to rearrange formatting
arguments because the word order may vary in different languages
<a href="#7">[7]</a>. For example:
</p>

<pre class="example">
<code>printf("String `%s' has %d characters\n", string, length(string)));</code>
</pre>

<p>A possible German translation of the format string might be:</p>

<pre class="example">
<code>"%2$d Zeichen lang ist die Zeichenkette `%1$s'\n"</code>
</pre>

<p>
using POSIX positional arguments <a href="#2">[2]</a>. Unfortunately these
positional specifiers are not portable <a href="#6">[6]</a>. The C++ I/O
streams don't support such rearranging of arguments by design because they
are interleaved with the portions of the literal string:
</p>

<pre class="example">
<code>cout << "String `" << string << "' has " << length(string) << " characters\n";</code>
</pre>

<p>
The current proposal allows both positional and automatically numbered
arguments, for example:
</p>

<pre class="example">
<code>fmt::format("String `{}' has {} characters\n", string, length(string)));</code>
</pre>

<p>with the German translation of the format string:</p>

<pre class="example">
<code>"{1} Zeichen lang ist die Zeichenkette `{0}'\n"</code>
</pre>

<h3><a name="Performance">Performance</a></h3>

<p>
The formatting library has been designed with performance in mind. It tries to
minimize the number of virtual function calls and dynamic memory allocations
done per a formatting operation. In particular, if formatting output can fit
into a fixed-size buffer allocated on stack, it should be possible to avoid
them altogether by using a suitable API.
</p>

<p>
To this end, a buffer abstraction represented by the
<code>fmt::basic_buffer</code> template is introduced. A buffer is a contiguous
block of memory that can be accessed directly and can optionally grow. Only one
virtual function, <code>grow</code>, needs to be called during formatting and
only when the buffer is not large enough.
</p>

<p>
The locale-independent formatting can also be implemented more efficiently than
the locale-aware one. However, the main goal for the former is to support
specific use cases (see <a href="Locale">Locale support</a>) rather than to
improve performance.
</p>

<h3><a name="Footprint">Binary footprint</a></h3>

<p>In order to minimize binary code size, each formatting function that uses
variadic templates is a small inline wrapper around its non-variadic
counterpart. This wrapper creates an object representing an array of argument
references with <code>fmt::make_args</code> and calls the non-variadic function
to do the actual work. For example, the <code>format</code> variadic function
calls <code>vformat</code>.</p>

<p>Multiple argument type codes can be combined and passed into a
formatting function as a single integer if the number of arguments is small.
Since argument types are known at compile time this can be an integer
constant and there will be no code generated to compute it, only to store
according to calling conventions.</p>

<p>Given a reasonable optimizing compiler, this will result in a compact
per-call binary code, effectively consisting of placing argument pointers
(or, possibly, copies for primitive types) and packed argument type codes on stack
and calling a formatting function.</p>

<h3><a name="StringView">Null-terminated string view</a></h3>

<p>The formatting library uses a null-terminated string view
<code>basic_cstring_view</code> instead of <code>basic_string_view</code>.
This results in somewhat smaller and faster code because the string size,
which is not used, doesn't have to be computed and passed. Also having
a termination character makes parsing easier.</p>

<h3><a name="Impact">Impact on existing code</a></h3>

<p>
The proposed formatting API is defined in the new header
<code>&lt;format&gt;</code> and should have no impact on existing code.
</p>

<h2><a name="Wording">Proposed wording</a></h2>

Insert a new section in 27.7 [iostream.format].

<h3>Header <code>&lt;format&gt;</code> synopsis</h3>

<pre>
<code>namespace std {
namespace fmt {

template &lt;class Context&gt;
class basic_arg;

template &lt;class Visitor, class Context&gt;
<i>see below</i> visit(Visitor&amp;&amp; vis, basic_arg&lt;Context&gt; arg);

template &lt;class Context, class ...Args&gt;
class arg_store;

template &lt;class Context&gt;
class basic_args;

template &lt;class Char&gt;
class basic_context;

typedef basic_context&lt;char&gt; context;
typedef basic_args&lt;context&gt; args;

template &lt;class ...Args&gt;
arg_store&lt;context, Args...&gt; make_args(const Args&amp;... args);

template &lt;class Context, class ...Args&gt;
arg_store&lt;Context, Args...&gt; make_args(const Args&amp;... args);

template &lt;class Char&gt;
class basic_buffer;

typedef basic_buffer&lt;char&gt; buffer;

template &lt;class Char&gt;
class basic_cstring_view;

typedef basic_cstring_view&lt;char&gt; cstring_view;

class format_error;

template &lt;class ...Args&gt;
string format(cstring_view format_str, const Args&amp;... args);

string vformat(cstring_view format_str, args args);

template &lt;class ...Args&gt;
string format_to(buffer&amp; buf, cstring_view format_str, const Args&amp;... args);

string vformat_to(buffer&amp; buf, cstring_view format_str, args args);

template &lt;class Char, class T&gt;
void format_value(basic_buffer&lt;Char&gt;&amp; buf, const T&amp; value, basic_context&lt;Char&gt;&amp; ctx);
}  // namespace fmt
}  // namespace std </code>
</pre>

<h3><a name="SyntaxRef">Format string syntax</a></h3>

<p>
Format strings contain <em>replacement fields</em> surrounded by curly braces
<code>{}</code>. Anything that is not contained in braces is considered literal
text, which is copied unchanged to the output. A brace character can be
included in the literal text by doubling: <code>{{</code> and <code>}}</code>.
</p>

<p>
The grammar for a replacement field is as follows:
</p>

<!-- The notation is the same as in n4296 22.4.3.1. -->
<pre>
<code>replacement-field ::=  '{' [arg-id] [':' format-spec] '}'
arg-id            ::=  integer
integer           ::=  digit+
digit             ::=  '0'...'9'</code>
</pre>

<p>
In less formal terms, the replacement field can start with an
<code>arg-id</code> that specifies the argument whose value is to be formatted
and inserted into the output instead of the replacement field. The
<code>arg-id</code> is optionally followed by a <code>format-spec</code>,
which is preceded by a colon <code>':'</code>. These specify a non-default
format for the replacement value.
</p>

<p>
See also the <a href="FormatSpec">Format specification mini-language</a>
section.
</p>

<p>
If the numerical <code>arg-id</code>s in a format string are 0, 1, 2, ... in
sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ...
will be automatically inserted in that order.
</p>

<p>
Some simple format string examples:
</p>

<pre>
<code>"First, thou shalt count to {0}" // References the first argument
"Bring me a {}"                  // Implicitly references the first argument
"From {} to {}"                  // Same as "From {0} to {1}"</code>
</pre>

<p>
The <code>format-spec</code> field contains a specification of how the value
should be presented, including such details as field width, alignment, padding,
decimal precision and so on. Each value type can define its own <em>formatting
mini-language</em> or interpretation of the <code>format-spec</code>.
</p>

<p>
Most built-in types support a common formatting mini-language, which is
described in the next section.
</p>

<p>
A <code>format-spec</code> field can also include nested replacement fields
in certain position within it. These nested replacement fields can contain only
an argument index; format specifications are not allowed. This allows the
formatting of a value to be dynamically specified.
</p>

<h4><a name="FormatSpec">Format specification mini-language</a></h4>

<p>
<em>Format specifications</em> are used within replacement fields contained
within a format string to define how individual values are presented (see
<a href="#SyntaxRef">Format string syntax</a>). Each formattable type may define
how the format specification is to be interpreted.
</p>

<p>
Most built-in types implement the following options for format specifications,
although some of the formatting options are only supported by the numeric types.
</p>

<p>
The general form of a <em>standard format specifier</em> is:
</p>

<pre>
<code>format-spec ::=  [[fill] align] [sign] ['#'] ['0'] [width] ['.' precision] [type]
fill        ::=  &lt;a character other than '{' or '}'&gt;
align       ::=  '<' | '>' | '=' | '^'
sign        ::=  '+' | '-' | ' '
width       ::=  integer | '{' arg-id '}'
precision   ::=  integer | '{' arg-id '}'
type        ::=  int-type | 'a' | 'A' | 'c' | 'e' | 'E' | 'f' | 'F' | 'g' | 'G' | 'p' | 's'
int-type    ::=  'b' | 'B' | 'd' | 'o' | 'x' | 'X'</code>
</pre>

<p>
The <code>fill</code> character can be any character other than <code>'{'</code>
or <code>'}'</code>. The presence of a fill character is signaled by the
character following it, which must be one of the alignment options. If the
second character of <code>format-spec</code> is not a valid alignment option,
then it is assumed that both the fill character and the alignment option are
absent.

<p>
The meaning of the various alignment options is as follows:
</p>

<table>
<thead>
<tr><th>Option</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'&lt;'</code></td>
<td>Forces the field to be left-aligned within the available space (this is
    the default for most objects).</td>
</tr>
<tr>
<td><code>'&gt;'</code></td>
<td>Forces the field to be right-aligned within the available space (this is
    the default for numbers).</td>
</tr>
<tr>
<td><code>'='</code></td>
<td>Forces the padding to be placed after the sign (if any) but before the
    digits. This is used for printing fields in the form
    <code>+000000120</code>. This alignment option is only valid for numeric
    types.</td>
</tr>
<tr>
<td><code>'^'</code></td>
<td>Forces the field to be centered within the available space.</td>
</tr>
</tbody>
</table>

<p>
Note that unless a minimum field width is defined, the field width will always
be the same size as the data to fill it, so that the alignment option has no
meaning in this case.
</p>

<p>
The <code>sign</code> option is only valid for number types, and can be one of
the following:
</p>

<table>
<thead>
<tr><th>Option</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'+'</code></td>
<td>Indicates that a sign should be used for both positive as well as negative
    numbers.</td>
</tr>
<tr>
<td><code>'-'</code></td>
<td>Indicates that a sign should be used only for negative numbers (this is
    the default behavior).</td>
</tr>
<tr>
<td>space</td>
<td>Indicates that a leading space should be used on positive numbers, and a
    minus sign on negative numbers.</td>
</tr>
</tbody>
</table>

<p>
The <code>'#'</code> option causes the <em>alternate form</em> to be used for
the conversion. The alternate form is defined differently for different types.
This option is only valid for integer and floating-point types. For integers,
when binary, octal, or hexadecimal output is used, this option adds the prefix
respective <code>"0b"</code> (<code>"0B"</code>), <code>"0"</code>, or
<code>"0x"</code> (<code>"0X"</code>) to the output value. Whether the prefix
is lower-case or upper-case is determined by the case of the type specifier,
for example, the prefix <code>"0x"</code> is used for the type <code>'x'</code>
and <code>"0X"</code> is used for <code>'X'</code>. For floating-point numbers
the alternate form causes the result of the conversion to always contain a
decimal-point character, even if no digits follow it. Normally, a decimal-point
character appears in the result of these conversions only if a digit follows it.
In addition, for <code>'g'</code> and <code>'G'</code> conversions, trailing
zeros are not removed from the result.
</p>

<p>
<code>width</code> is a decimal integer defining the minimum field width. If
not specified, then the field width will be determined by the content.
</p>

<p>
Preceding the <code>width</code> field by a zero (<code>'0'</code>) character
enables sign-aware zero-padding for numeric types. This is equivalent to a
<code>fill</code> character of <code>'0'</code> with an <code>alignment</code>
type of <code>'='</code>.
</p>

<p>
The <code>precision</code> is a decimal number indicating how many digits should
be displayed after the decimal point for a floating-point value formatted with
<code>'f'</code> and <code>'F'</code>, or before and after the decimal point
for a floating-point value formatted with <code>'g'</code> or <code>'G'</code>.
For non-number types the field indicates the maximum field size - in other
words, how many characters will be used from the field content. The
<code>precision</code> is not allowed for integer, character, Boolean, and
pointer values.
</p>

<p>
Finally, the <code>type</code> determines how the data should be presented.
</p>

<p>The available string presentation types are:</p>

<table>
<thead>
<tr><th>Type</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'s'</code></td>
<td>String format. This is the default type for strings and may be omitted.</td>
</tr>
<tr>
<td>none</td>
<td>The same as <code>'s'</code>.</td>
</tr>
</tbody>
</table>

<p>The available character presentation types are:</p>

<table>
<thead>
<tr><th>Type</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'c'</code></td>
<td>Character format. This is the default type for characters and may be
    omitted.</td>
</tr>
<tr>
<td>none</td>
<td>The same as <code>'c'</code>.</td>
</tr>
</tbody>
</table>

<p>The available integer presentation types are:</p>

<table>
<thead>
<tr><th>Type</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'b'</code></td>
<td>Binary format. Outputs the number in base 2. Using the <code>'#'</code>
    option with this type adds the prefix <code>"0b"</code> to the output
    value.</td>
</tr>
<tr>
<td><code>'B'</code></td>
<td>Binary format. Outputs the number in base 2. Using the <code>'#'</code>
    option with this type adds the prefix <code>"0B"</code> to the output
    value.</td>
</tr>
<tr>
<td><code>'d'</code></td>
<td>Decimal integer. Outputs the number in base 10.</td>
</tr>
<tr>
<td><code>'o'</code></td>
<td>Octal format. Outputs the number in base 8.</td>
</tr>
<tr>
<td><code>'x'</code></td>
<td>Hex format. Outputs the number in base 16, using lower-case letters for the
    digits above 9. Using the <code>'#'</code> option with this type adds the
    prefix <code>"0x"</code> to the output value.</td>
</tr>
<tr>
<td><code>'X'</code></td>
<td>Hex format. Outputs the number in base 16, using upper-case letters for the
    digits above 9. Using the <code>'#'</code> option with this type adds the
    prefix <code>"0X"</code> to the output value.</td>
</tr>
<tr>
<td><code>'n'</code></td>
<td>Number. This is the same as <code>'d'</code>, except that it uses the
    buffer's locale to insert the appropriate number separator characters.</td>
</tr>
<tr>
<td>none</td>
<td>The same as <code>'d'</code>.</td>
</tr>
</tbody>
</table>

<p>
Integer presentation types can also be used with character and Boolean values.
Boolean values are formatted using textual representation, either true or false,
if the presentation type is not specified.
</p>

<p>The available presentation types for floating-point values are:</p>

<table>
<thead>
<tr><th>Type</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'a'</code></td>
<td>Hexadecimal floating point format. Prints the number in base 16 with prefix
    <code>"0x"</code> and lower-case letters for digits above 9. Uses
    <code>'p'</code> to indicate the exponent.</td>
</tr>
<tr>
<td><code>'A'</code></td>
<td>Same as <code>'a'</code> except it uses upper-case letters for the prefix,
    digits above 9 and to indicate the exponent.</td>
</tr>
<tr>
<td><code>'e'</code></td>
<td>Exponent notation. Prints the number in scientific notation using the
    letter <code>'e'</code> to indicate the exponent.</td>
</tr>
<tr>
<td><code>'E'</code></td>
<td>Exponent notation. Same as <code>'e'</code> except it uses an upper-case
    <code>'E'</code> as the separator character.</td>
</tr>
<tr>
<td><code>'f'</code></td>
<td>Fixed point. Displays the number as a fixed-point number.</td>
</tr>
<tr>
<td><code>'F'</code></td>
<td>Fixed point. Same as <code>'f'</code>, but converts <code>nan</code> to
    <code>NAN</code> and <code>inf</code> to <code>INF</code>.</td>
</tr>
<tr>
<td><code>'g'</code></td>
<td>General format. For a given precision <code>p >= 1</code>, this rounds the
    number to <code>p</code> significant digits and then formats the result in
    either fixed-point format or in scientific notation, depending on its
    magnitude.

    A precision of <code>0</code> is treated as equivalent to a precision of
    <code>1</code>.</td>
</tr>
<tr>
<td><code>'n'</code></td>
<td>Number. This is the same as <code>'g'</code>, except that it uses the
    buffer's locale to insert the appropriate number separator characters.</td>
</tr>
<tr>
<td>none</td>
<td>The same as <code>'g'</code>.</td>
</tr>
</tbody>
</table>

<p>The available presentation types for pointers are:</p>

<table>
<thead>
<tr><th>Type</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr>
<td><code>'p'</code></td>
<td>Pointer format. This is the default type for pointers and may be
    omitted.</td>
</tr>
<tr>
<td>none</td>
<td>The same as <code>'p'</code>.</td>
</tr>
</tbody>
</table>

<h3>Formatting functions</h3>

<dl>
<dt>
<code>template &lt;class ...Args&gt;<br>
&nbsp;&nbsp;string format(cstring_view format_str, const Args&amp;... args);</code>
</dt>
<dd>

<p>
<i>Effects</i>: The function returns a <code>string</code> object
constructed from the format string argument <code>format_str</code> with each
replacement field substituted with the character representation of the
argument it refers to, formatted according to the specification given in the
field.
</p>
<p><i>Returns</i>: The formatted string.</p>
<p><i>Throws</i>: <code>format_error</code> if <code>format_str</code> is not a
valid format string.</p>
</dd>
</dl>

<dl>
<dt>
<code>string vformat(cstring_view format_str, fmt::args args);</code>
</dt>
<dd>
<p>
<i>Effects</i>: The function returns a <code>string</code> object
constructed from the format string argument <code>format_str</code> with each
replacement field substituted with the character representation of the
argument it refers to, formatted according to the specification given in the
field.
</p>
<p><i>Returns</i>: The formatted string.</p>
<p><i>Throws</i>: <code>format_error</code> if <code>format_str</code> is not a
valid format string.</p>
</dd>
</dl>

<dl>
<dt>
<code>template &lt;class ...Args&gt;<br>
&nbsp;&nbsp;void format_to(buffer&amp; buf, cstring_view format_str, const Args&amp;... args);</code>
</dt>
<dd>

<p>
<i>Effects</i>: The function appends to <code>buf</code> the format string
<code>format_str</code> with each replacement field substituted with the character
representation of the argument it refers to, formatted according to the
specification given in the field.
</p>
<p><i>Throws</i>: <code>format_error</code> if <code>format_str</code> is not a valid
format string.</p>
</dd>
</dl>

<dl>
<dt>
<code>template &lt;class ...Args&gt;<br>
&nbsp;&nbsp;void vformat_to(buffer&amp; buf, cstring_view format_str, fmt::args args);</code>
</dt>
<dd>

<p>
<i>Effects</i>: The function appends to <code>buf</code> the format string
<code>format_str</code> with each replacement field substituted with the
character representation of the argument it refers to, formatted according to
the specification given in the field.
</p>
<p><i>Throws</i>: <code>format_error</code> if <code>format_str</code> is not a
valid format string.</p>
</dd>
</dl>

<h3>Formatting argument</h3>

<pre>
<code>template &lt;class Context&gt;
class basic_arg {
public:
  basic_arg();

  explicit operator bool() const noexcept;

  bool is_integral() const;
  bool is_numeric() const;
  bool is_pointer() const;
};</code>
</pre>

<p>
An object of type <code>basic_arg&lt;Context&gt;</code> represents a reference
to a formatting argument parameterized on a formatting context (see
<a href="#gensection-7">3.9</a>). It can hold a value of one of the following
types:
<ul>
<li><code>int</code>
<li><code>unsigned int</code>
<li>integral types larger than <code>int</code>
<li><code>bool</code>
<li><code>Char</code>
<li><code>double</code>
<li>floating-point types larger than <code>double</code>
<li><code>const char*</code>
<li><code>string_view</code>
<li><code>basic_string_view&lt;Char&gt;</code> if different from
    <code>string_view</code>
<li><code>const void*</code>
<li>reference to an object of a user-defined type (implementation-defined)
<li><code>monostate</code> representing an empty state, i.e. when the
    object doesn't refer to an argument
</ul>
where <code>Char</code> is <code>typename Context::char_type</code>.
The value can be accessed via the visitation interface defined in the next
section.
</p>

<dl>
<dt><code>basic_arg();</code></dt>
<dd>
<p><i>Effects</i>: Constructs a <code>basic_arg</code> object that
doesn't refer to an argument.
</p>
<p><i>Postcondition</i>: <code>!(*this)</code>.</p>
</dd>
<dt><code>explicit operator bool() const noexcept;</code></dt>
<dd>
<p><i>Returns</i>: <code>true</code> if <code>*this</code> refers to an
argument, otherwise <code>false</code>.</p>
</dd>
<dt><code>bool is_integral() const;</code></dt>
<dd>
<p><i>Returns</i>: <code>true</code> if <code>*this</code> represents an
argument of an integral type.</p>
</dd>
<dt><code>bool is_numeric() const;</code></dt>
<dd>
<p><i>Returns</i>: <code>true</code> if <code>*this</code> represents an
argument of a numeric type.</p>
</dd>
<dt><code>bool is_pointer() const;</code></dt>
<dd>
<p><i>Returns</i>: <code>true</code> if <code>*this</code> represents an
argument of type <code>const void*</code>.</p>
</dd>
</dl>

<p><i>Complexity:</i> The invocation of <code>is_integral</code>,
<code>is_numeric</code>, and <code>is_pointer</code> does not depend on
the number of possible value types of a formatting argument.
</p>

<h3>Formatting argument visitation</h3>

<dl>
<dt><code>template &lt;class Visitor, class Context&gt;<br>
&nbsp;&nbsp;<i>see below</i> visit(Visitor&amp;&amp; vis, basic_arg&lt;Context&gt; arg);</code></dt>
<dd>
<p><i>Requires:</i>
The expression in the Effects section shall be a valid expression of the same
type, for all alternative value types of a formatting argument.
Otherwise, the program is ill-formed.</p>
<p><i>Effects:</i>
Let <code>value</code> be the value stored in the formatting argument
<code>arg</code>.
Returns <code>INVOKE(forward<Visitor>(vis), value);</code>.</p>
<p><i>Remarks:</i>
The return type is the common type of all possible <code>INVOKE</code>
expressions in the Effects section. Since exact value types are
implementation-defined, visitors should use type traits to handle multiple
types.
</p>
<p><i>Complexity:</i> The invocation of the callable object does not depend on
the number of possible values types of a formatting argument.
</p>
<p><i>Example:</i><pre>
<code>auto uint_value = visit([](auto value) {
  if constexpr (is_unsigned_v&lt;delctype(value)&gt;)
    return value;
  return 0;
}, arg);</code>
</pre>
</dd>
</dl>

<h3>Class template <code>arg_store</code></h3>

<pre>
<code>template &lt;class Context, class ...Args&gt;
class arg_store;</code>
</pre>

<p>
An object of type <code>arg_store</code> stores formatting arguments or
references to them.
</p>

<h3>Class template <code>basic_args</code></h3>

<pre>
<code>template &lt;class Context&gt;
class basic_args {
public:
  typedef <i>implementation-defined</i> size_type;

  basic_args() noexcept;

  template &lt;class ...Args&gt;
  basic_args(const arg_store&lt;Context, Args...&gt;&amp; store);

  basic_arg&lt;Context&gt; operator[](size_type i) const;
};</code>
</pre>

<p>
An object of type <code>basic_args</code> provides access to formatting
arguments. Copying a <code>basic_args</code> object does not copy the
arguments.
</p>

<dl>
<dt><code>basic_args() noexcept;</code></dt>
<dd>
<p><i>Effects</i>: Constructs an empty <code>basic_args</code> object.
</p>
<p><i>Postcondition</i>: <code>!(*this)[0]</code>.</p>
</dd>
</dl>

<dl>
<dt><code>template &lt;class ...Args&gt;<br>
basic_args(const arg_store&lt;Context, Args...&gt;&amp; store);</code></dt>
<dd>
<p><i>Effects</i>: Constructs a <code>basic_args</code> object that
provides access to the agruments in <code>store</code>.
</p>
</dd>
</dl>

<dl>
<dt><code>basic_arg&lt;Context&gt; operator[](size_type i) const;</code></dt>
<dd>
<p><i>Requires</i>: <code>i &lt;=</code> the number of formatting arguments
represented by the <code>basic_args</code> object.</p>
<p><i>Returns</i>: A <code>basic_arg</code> object that represents an argument
at index <code>i</code> if <code>i &lt;</code> the number of arguments.
Otherwise, returns an empty <code>basic_arg</code> object.</p>
</dd>
</dl>

<h3>Function template <code>make_args</code></h3>

<dl>
<dt>
<code>template &lt;class ...Args&gt;<br>
arg_store&lt;context, Args...&gt; make_args(const Args&amp;... args);</code>
</dt>
<dd>

<p>
<i>Effects</i>: The function returns an <code>arg_store</code> object
that stores references to or copies of formatting arguments <code>args</code>.
</p>
<p><i>Returns</i>: The <code>arg_store</code> object constructed from
formatting arguments.</p>
</dd>
</dl>

<h3>Formatting context</h3>

<pre>
<code>template &lt;class Char&gt;
class basic_context {
public:
  typedef Char char_type;
  typedef basic_args&lt;basic_context&gt; args_type;

  basic_context(const Char* format_str, args_type args);

  const Char*&amp; ptr();

  args_type args() const;
};</code>
</pre>

<p>
The class <code>basic_context</code> represents a formatting context for
user-defined types. It provides access to formatting arguments and the current
position in the format string being parsed.
</p>

<dl>
<dt><code>basic_context(const Char* format_str, args_type args);</code></dt>
<dd>
<p><i>Effects</i>: Constructs an object of class <code>basic_context</code>
storing references to the formatting arguments and the format string in it.
</p>
<p><i>Postcondition</i>: <code>ptr() == format_str</code>.</p>
</dd>
<dt><code>const Char*&amp; ptr();</code></dt>
<dd>
<p><i>Effects</i>: Returns a pointer to the current position in the format
string being parsed.</p>
</dd>
<dt><code>args_type args() const;</code></dt>
<dd>
<p><i>Effects</i>: Returns a copy of the <code>args</code> object that was
passed to the constructor of <code>basic_context</code>.</p>
</dd>
</dl>

<h3>Formatting buffer</h3>

<pre>
<code>template &lt;class Char&gt;
class basic_buffer {
public:
  typedef <i>implementation-defined</i> size_type;

  virtual ~basic_buffer();

  size_type size() const noexcept;
  size_type capacity() const noexcept;

  void resize(size_type sz);
  void reserve(size_type n);

  Char* data() noexcept;
  const Char* data() const noexcept;

  void push_back(const Char&amp; x);

  template &lt;class InputIterator&gt;
  void append(InputIterator first, InputIterator last);

  virtual locale locale() const;

protected:
  basic_buffer() noexcept;

  void set(Char* s, size_type n) noexcept;

  virtual void grow(size_type n) = 0;
};</code>
</pre>

<p>
The class <code>basic_buffer&lt;T&gt;</code> represents a contiguous
memory buffer with an optional growing ability. An instance of
<code>basic_buffer&lt;T&gt;</code> stores elements of type <code>T</code>.
The elements of a <code>basic_buffer</code> are stored contiguously, meaning
that if <code>b</code> is a <code>basic_buffer&lt;T&gt;</code> then it obeys
the identity <code>&amp;b.data()[n] == &amp;b.data()[0] + n</code> for
all <code>0 &lt;= n &lt; d.size()</code>.
</p>

<dl>
<dt><code>basic_buffer() noexcept;</code></dt>
<dd>
  <p><i>Effects</i>: Constructs an empty buffer.</p>
  <p><i>Postcondition</i>: <code>size() == 0</code>.</p>
</dd>
<dt><code>set(Char* s, size_type n) noexcept;</code></dt>
<dd>
  <p><i>Effects</i>: Sets data and capacity.</p>
  <p><i>Postcondition</i>: <code>data() == s</code> and
  <code>capacity() == n</code>.</p>
</dd>
<dt><code>size_type size() const noexcept;</code></dt>
<dd>
  <p><i>Returns</i>: The buffer size.</p>
</dd>
<dt><code>size_type capacity() const noexcept;</code></dt>
<dd>
  <p><i>Returns</i>: The total number of elements that the buffer can hold
  without requiring reallocation.</p>
</dd>
<dt><code>void resize(size_type sz);</code></dt>
<dd>
  <p><i>Effects</i>: If <code>sz &lt;= size()</code>, removes last
  <code>size() - sz</code> elements from the buffer.
  If <code>size() &lt; sz</code>, appends <code>sz - size()</code>
  default-initialized elements to the buffer.</p>
  <p><i>Postcondition</i>: <code>size() == sz</code>.</p>
</dd>
<dt><code>void reserve(size_type n);</code></dt>
<dd>
  <p><i>Requires</i>: <code>T</code> shall be <code>MoveInsertable</code> into
  <code>*this.</code></p>
  <p><i>Effects</i>: A directive that informs a buffer of a planned change in
  size, so that it can manage the storage allocation accordingly. After
  <code>reserve()</code>, <code>capacity()</code> is greater or equal to the
  argument of <code>reserve</code> if reallocation happens; and equal to the
  previous value of <code>capacity()</code> otherwise. Reallocation happens
  at this point if and only if the current capacity is less than the argument of
  <code>reserve()</code>, and it is performed by calling <code>grow(n)</code>.
  If an exception is thrown other than by the move constructor of a
  non-<code>CopyInsertable</code> type, there are no effects.</p>
</dd>
<dt><code>void grow(size_type n);</code></dt>
<dd>
  <p><i>Requires</i>: <code>n &gt; capacity()</code>.</p>
  <p><i>Effects</i>: Reallocates the buffer to increase its capacity to at least
  <code>n</code> in a way that is defined separately for each class derived
  from <code>basic_buffer</code>.</p>
  <p><i>Throws</i>: <code>length_error</code> if <code>n</code> exceeds a limit
  defined by a derived class, in particular, if the latter has a fixed capacity.
  </p>
</dd>
<dt><code>Char* data() noexcept;<br>
  const Char* data() const noexcept;</code></dt>
<dd>
  <p><i>Returns</i>: A pointer such that <code>[data(), data() + size())</code>
  is a valid range.</p>
</dd>
<dt><code>void push_back(const Char&amp; x);</code></dt>
<dd>
  <p><i>Effects</i>: Equivalent to <code>append(&amp;x, &amp;x + 1)</code>.</p>
</dd>
<dt><code>template &lt;class InputIterator&gt;<br>
  void append(InputIterator first, InputIterator last);</code>
  <p>Let <code>n</code> be the number of elements in the range
    <code>[first, last)</code>.</p>
</dt>
<dd>
  <p><i>Requires</i>: <code>[first, last)</code> is a valid range.</p>
  <p><i>Throws</i>: <code>length_error</code> if <code>size() + n &gt;
  capacity()</code> and exceeds the capacity limit defined by a derived
  class.</p>
  <p><i>Effects</i>: The function replaces the buffer controlled by
  <code>*this</code> with a buffer of length <code>size() + n</code> whose first
  <code>size()</code> elements are a copy of the original buffer controlled by
  <code>*this</code> and whose remaining elements are a copy of the elements
  in the range.
  </p>
</dd>
<dt><code>locale locale() const;</code></dt>
<dd>
  <p><i>Returns</i>: The locale to be used for locale-specific formatting.
  The default implementation returns a copy of the global C++ locale but derived
  classes may return different locales.</p>
</dd>
</dl>

<h3>Format string</h3>

<pre>
<code>template &lt;class Char&gt;
class basic_cstring_view {
public:
  basic_cstring_view(const basic_string&lt;Char&gt;&amp; str);
  basic_cstring_view(const Char* str);

  const Char* c_str() const noexcept;
};</code>
</pre>

<p>
The class <code>basic_cstring_view</code> represents a null-terminated string
view.
</p>

<dl>
<dt><code>basic_cstring_view(const basic_string&lt;Char&gt;&amp; str);</code></dt>
<dd>
  <p><i>Effects</i>: Constructs an object of class <code>basic_cstring_view</code>.
  </p>
  <p><i>Postcondition</i>: <code>c_str() == str.c_str()</code>.
  </p>
</dd>
<dt><code>basic_cstring_view(const Char* str);</code></dt>
<dd>
  <p><i>Effects</i>: Constructs an object of class <code>basic_cstring_view</code>.
  </p>
  <p><i>Postcondition</i>: <code>c_str() == str</code>.
  </p>
</dd>
<dt><code>const Char* c_str() const noexcept;</code></dt>
<dd>
  <p><i>Returns</i>: A pointer to the string.</p>
</dd>
</dl>

<h3>User-defined types</h3>

<p>
If a format string refers to an object of a user-defined type as in

<pre class="example">
<code>X x;
string s = format("{}", x);
</code>
</pre>

the formatting function will call <code>format_value(buf, x, ctx)</code>,
where <code>buf</code> is a reference to the formatting buffer, <code>x</code>
is a const reference to the argument and <code>ctx</code> is a reference to
the formatting context. <code>ctx.ptr()</code> will point to one of the
following positions in the format string being parsed:
</p>

<ul>
<li><code>':'</code> preceding <code>format-spec</code> for the current
argument,
<li><code>'}'</code> if there is no <code>format-spec</code>.
</ul>

<p>
The <code>format_value</code> function should parse <code>format-spec</code>,
format the argument and advance <code>ctx.ptr()</code> to point to
<code>'}'</code> that ends <code>replacement-field</code> for the current
argument.
</p>

<p>
The default implementation of <code>format_value</code> calls ostream insertion
<code>operator&lt;&lt;</code> to format the value.
</p>

<dl>
<dt>
<code>template &lt;class Char, class T&gt;<br>
void format_value(basic_buffer&lt;Char&gt;&amp; buf, const T&amp; value, basic_context&lt;Char&gt;&amp; ctx);
</code>
</dt>
<dd>

<p>
<i>Effects</i>: The function calls <code>os &lt;&lt; value</code>, where
<code>os</code> is an instance of <code>std::basic_ostream&lt;Char&gt;</code>
with a stream buffer writing to <code>buf</code>.
</p>
<p><i>Throws</i>: <code>format_error</code> if <code>*ctx.ptr() != '}'</code>.</p>
</dd>
</dl>

<h3>Error reporting</h3>

<pre>
<code>class format_error : public runtime_error {
public:
  explicit format_error(const string&amp; what_arg);
  explicit format_error(const char* what_arg);
};</code>
</pre>

<p>
The class <code>format_error</code> defines the type of objects thrown as
exceptions to report errors from the formatting library.
</p>

<dl>
<dt><code>format_error(const string&amp; what_arg);</code></dt>
<dd>
  <p><i>Effects</i>: Constructs an object of class <code>format_error</code>.
  </p>
  <p><i>Postcondition</i>: <code>strcmp(what(), what_arg.c_str()) == 0</code>.
  </p>
</dd>
<dt><code>format_error(const char* what_arg);</code></dt>
<dd>
  <p><i>Effects</i>: Constructs an object of class <code>format_error</code>.
  </p>
  <p><i>Postcondition</i>: <code>strcmp(what(), what_arg) == 0</code>.</p>
</dd>
</dl>

<h2><a name="RelatedWork">Related work</a></h2>

<p>
The Boost Format library [8] is an established formatting library that uses
printf-like format string syntax with extensions. The main differences between
this library and the current proposal are:
</p>

<ul>
<li>Syntax: for the reasons descibed in section
<a href="Syntax">Format String Syntax</a> this proposal
uses a new syntax instead of extending the  printf one. This allows much
simpler and easier to parse grammar, not burdened by legacy specifiers used to
convey type information. For example, Boost Format has two ways
to refer to an argument by index and allows but ignores some format specifiers.
<li>API: Boost Format uses <code>operator%</code> to pass formatting arguments
while this proposal uses variadic function templates.
<li>Performance: The implementation of this proposal is several times faster
that the implementation of Boost Format on tinyformat benchmarks [9],
generates smaller binary code and is faster to compile.
</ul>

<p>
A printf-like Interface for the Streams Library [10] is similar to the Boost
Format library but uses variadic templates instead of <code>operator%</code>.
Unfortunately it hasn't been updated since 2013 and the same arguments about
format string syntax apply to it.
</p>

<p>
The FastFormat library [11] is another well-known formatting library.
Similarly to this proposal, FastFormat uses brace-delimited format specifiers,
but otherwise the format string syntax is different and the library has
significant limitations [12]:

<blockquote>
Three features that have no hope of being accommodated within the current
design are:

<ul>
<li>Leading zeros (or any other non-space padding)
<li>Octal/hexadecimal encoding
<li>Runtime width/alignment specification
</ul>
</blockquote>
</p>

<p>
Formatting facilities of the Folly library [13] are the closest to the current
proposal. Folly also uses Python-like format string syntax nearly identical
to the one described here. However, the API details are quite different. The current
proposal tries to address performance and code bloat issues that are largely
ignored by Folly Format. For instance formatting functions in Folly Format
are parameterized on all argument types while in this proposal, only the inlined
wrapper functions are, which results in much smaller binary code and better compile
times.
</p>

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

<p>
An implementation of this proposal is available in the <code>std</code> branch
of the open-source fmt library [14].
</p>

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

The Format String Syntax section is based on the Python documentation [3].

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

<p>
<a name="1">[1]</a>
<cite>The <code>fprintf</code> function. ISO/IEC 9899:2011. 7.21.6.1.</cite><br>
<a name="2">[2]</a>
<cite><a href="http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html">
fprintf, printf, snprintf, sprintf - print formatted output</a>. The Open
Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 Edition.</cite><br>
<a name="3">[3]</a>
<cite><a href="https://docs.python.org/3/library/string.html#format-string-syntax">
6.1.3. Format String Syntax</a>. Python 3.5.2 documentation.</cite><br>
<a name="4">[4]</a>
<cite><a href="https://msdn.microsoft.com/en-us/library/system.string.format(v=vs.110).aspx">
String.Format Method</a>. .NET Framework Class Library.</cite><br>
<a name="5">[5]</a>
<cite><a href="https://doc.rust-lang.org/std/fmt/">
Module <code>std::fmt</code></a>. The Rust Standard Library.</cite><br>
<a name="6">[6]</a>
<cite><a href="https://msdn.microsoft.com/en-us/library/56e442dc(v=vs.120).aspx">
Format Specification Syntax: printf and wprintf Functions</a>. C++ Language and
Standard Libraries.</cite><br>
<a name="7">[7]</a>
<cite><a href="ftp://ftp.gnu.org/old-gnu/Manuals/gawk-3.1.0/html_chapter/gawk_11.html">
10.4.2 Rearranging printf Arguments</a>. The GNU Awk User's Guide.</cite><br>
<a name="8">[8]</a>
<cite><a href="http://www.boost.org/doc/libs/1_63_0/libs/format/">
Boost Format library</a>. Boost 1.63 documentation.</cite><br>
<a name="9">[9]</a>
<cite><a href="https://github.com/fmtlib/fmt#speed-tests">
Speed Test</a>. The fmt library repository.</cite><br>
<a name="10">[10]</a>
<cite><a href="https://isocpp.org/files/papers/n3716.html">
A printf-like Interface for the Streams Library (revision 1)</a>.</cite><br>
<a name="11">[11]</a>
<cite><a href="http://www.fastformat.org/">
The FastFormat library website</a>.</cite><br>
<a name="12">[12]</a>
<cite><a href="https://accu.org/index.php/journals/1539">
An Introduction to Fast Format (Part 1): The State of the Art</a>.
Overload Journal #89 - February 2009</cite><br>
<a name="13">[13]</a>
<cite><a href="https://github.com/facebook/folly">
The folly library repository</a>.</cite><br>
<a name="14">[14]</a>
<cite><a href="https://github.com/fmtlib/fmt">
The fmt library repository</a>.</cite><br>
</p>

</div>
</body>
