Text Formatting

Revision History

Changes since R9

• Rebase wording onto the pre-Cologne C++ working draft N4820, in particular updating the section number from 19 to 20.
• Change "A format string is a possibly empty sequence of zero or more" to "A format string is a (possibly empty) sequence of" in [format.string].
• Replace "digit separator characters including the decimal radix separator" with "digit group separator characters" in the integer presentation types table in [format.string] since decimal radix separator doesn't apply to integer types.
• Replace "digit separator characters including the decimal radix separator" with "digit group and decimal radix separator characters" in the floating-point presentation types table in [format.string] to clarify what separator characters are.
• Replace "satisfies the OutputIterator<const charT&> requirements" with "satisfies OutputIterator<const charT&>" per Specification Style Guidelines.
• Clarify the semantics of operator + in [format.functions].
• Replace Mandates with a precondition that formatter<T_i, charT> meets the Formatter requirements in format_to_n, formatted_size, and make_format_args. Other functions get this precondition transitively via make_format_args.
• Replace "will meet the Formatter requirements" with "meets the Formatter requirements" in [format.formatter].
• Merge the precondition into Remarks getting rid of the unorthodox use of is_constant_evaluated in basic_format_parse_context::check_arg_id.
• Clarify how an implementation determines if typename Context::template formatter_type<T> is enabled in basic_format_arg.
• Replace "Let charT be decltype(fmt)::value_type." with "Let charT be the character type of the format string." and move it to the first paragraph of [format.string].
• Change three occurrences of the construct of the form "A if B, C otherwise" with "if B, A; otherwise, C" in the floating-point and pointer presentation tables [format.string] for readability.
• Add "unless specified otherwise" after "Formatting of objects of arithmetic types and const void* is done as if by calling to_chars" in [format.string] because infinity and NaN do not delegate to to_chars.
• Clarify that infinity and NaN are formatted as "inf" and "nan" for lower-case presentation types and "INF" and "NAN" for upper-case ones in [format.string].
• Replace "Out models OutputIterator<const charT&>. formatter" with "Out models OutputIterator<const charT&>, and formatter" in format_to_n to avoid potential confusion that formatter is a member.

Changes since R8

• Handle the case of undefined uintptr_t in [format.string].
• Clarify that digit separator characters include the decimal radix separator in [format.string].
• Clarify that a format string is a possibly empty sequence in [format.string].
• Add the default value for num_args in basic_format_parse_context to match the declaration in synopsis.
• Add a Remarks clause to basic_format_parse_context::check_arg_id.
• Add missing forward in [format.visit].
• Fix namespace qualification in example in [format.context].
• Replace Requires with Constraints, Mandates, and Expects as appropriate in vformat_to, format_to_n, formatted_size, and make_format_args per p1369.
• Replace "satisfies the X requirements" with "meets the X requirements" when referring to old-style requirements throughout the paper.
• Replace the undocumented Formattable requirement with the requirement that formatter<T, charT> is enabled in format_to_n, formatted_size, and make_format_args.
• Replace "A format string consists" with "A format string is a sequence" in [format.string].
• Replace "A format string is invalid if it contains a mix of automatic and manual indexing." with "A format string does not contain a mixture of automatic and manual indexing." in [format.string].
• Replace "Places the character representation" with "Places the first M characters of the character representation" in the specifications of format_to_n.
• Add missing std namespace qualifications in the formatter specialization example in [format.formatter].
• Add a colon after "provides enabled specializations" in [format.formatter].
• Add a missing charT template argument to formatter in the definition of basic_format_context::formatter_type in [format.context].
• Replace "Parses the range [pc.begin(), pc.end()) according to format specifications for type T until the first unmatched character" with "Parses format-spec ([format.string]) for type T in the range [pc.begin(), pc.end()) until the first unmatched character" in Table � — Formatter requirements.
• Remove "format string" from "format string range [pc.begin(), pc.end())" in Table � — Formatter requirements.
• Replace "Does not modify u" with "As above but does not modify u" in Table � — Formatter requirements.
• Clarify "id is a valid argument id" in the Expects clause in basic_format_parse_context::check_arg_id using a new exposition-only num_args_ member.
• Fix a typo: "back_insert_iterato" -> "back_insert_iterator" in [format.context].
• Rephrase the note in [format.context] to clarify that it applies to types other than char too.
• Replace "Requires: Out models OutputIterator<const charT&>" with "Out shall model OutputIterator<const charT&>" in [format.context].
• Change the type of width_arg_id from int to size_t in the example in [format.context].
• Make exposition-only code private and add exposition-only friends in [format.arg] for the code to remain well-formed.
• Disallow specializations of basic_format_arg ([format.arg]).
• Merge integral and unconstrained overloads of the basic_format_arg constructor to support specializations of formatter for extended integer types larger than long long int.
• Replace "a standard (un)signed integer type or an extended (un)signed integer type" with "a(n) (un)signed integer type" in basic_format_arg(const T&).
• Add "otherwise" to bullet points in basic_format_arg(const T&).
• Replace "the program is ill-formed" bullet point with "Constraints: typename Context::template formatter_type<T> is enabled" in basic_format_arg(const T&).
• Move the description of class basic_format_arg::handle before the definition.
• Replace &val with addressof(val) in the basic_format_arg::handle constructor.
• Simplify make_wformat_args by specifying it in terms of make_format_args.
• Move sections [format.make_args] and [format.make_wargs] next to section [format.arg_store].

Changes since R7

• Suggest placing 20.� Formatting as a subclause after 20.19 Primitive numeric conversions in the "General utilities library summary" table.
• Replace concept-related annotations with Requires clauses per P1369 Guidelines for Formulating Library Semantics Specifications.
• Rename O to Out in template parameters to make them distinguishable from 0.
• Replace "Returns:" with "Effects: Equivalent to:" in format and format_to specifications to propagate Throws.
• Merge the two format_to specifications into one.
• Add commas around "formatted according to specifications given in fmt" in the specifications of vformat_to and format_to_n.
• Replace "N is/be the formatted output size" with N = formatted_size(fmt, args...) in the specifications of vformat_to and format_to_n.
• Denote min(max(n, 0), N) by M in the specification of format_to_n since N is already taken.
• Require that each T_i in Args satisfies the Formattable requirements in the specifications of format_to_n, formatted_size, make_format_args, and make_wformat_args. Other functions get this transitively via make_(w)format_args.
• Move the format string specification to the new section [format.string].
• Remove the word "valid" when referring to a format string.
• Replace "The fmt string" with "A format string" in [format.string].
• Replace "by" with "for" in "Some of the formatting options are only supported by arithmetic types."
• Clarify that padding is placed after the prefix if any when using the numeric alignment and add an example.
• Rename "number separator" to "digit separator".
• Added a note that pointer presentation types also apply to nullptr_t.
• Replace "where charT is char or wchar_t" with "Let charT be either char or wchar_t" in [format.formatter].
• Clarify that infinity and NaN are formatted as "inf" and "nan" for non-uppercase specifiers in [format.string].
• Reword the definitions of PC, FC, pc, and fc in [formatter.requirements].
• Remove several occurrences of "shall" in Table � — Formatter requirements.
• Replace Returns and Remarks with Effects in [format.visit].
• Use kebab case for exposition-only types renaming format_arg_store to format-arg-store and basic_format_arg::char_type to basic_format_arg::char-type.
• Add a description of format-arg-store in [format.arg_store].
• Clarify what can be used as an iterator in format_context in [format.context].
• Remove unnecessary std qualifications.
• Remove noexcept from basic_format_arg(const char_type* s) because it has a precondition.

Changes since R6

• Rebase wording onto the pre-Kona C++ working draft N4800.
• Use placeholder for section and table numbers and drop "utilities" from the section name.
• Clarify the parse wording in Table � — Formatter requirements.
• Add an entry to the "General utilities library summary" table.
• Replace overload resolution Remarks with Constraints per p1369.
• Remove "shall" from Expects wording.
• Add Kona LEWG poll results for R6.
• Minor improvements to the wording and editing notes.

Changes since R5

• Separate parsing context from formatting context and remove basic_format_context::parse_context().
• Require that id in basic_format_parse_context::check_arg_id is a valid argument id.
• Replace Requires with Expects per p1369.

LEWG polls (R6):

SF	F	N	A	SA
7	2	0	0	0

Unanimous consent to all other design changes presented.

SF	F	N	A	SA
8	4	0	0	0

string message = format("The answer is {}.", 42);

printf("%*s", 10, "foo");
format("{:{}}", "foo", 10);

format("{:*^30}", "centered");

replacement-field ::= '{' [arg-id] [':' format-spec] '}'

time_t t = time(nullptr);
string date = format("The date is {0:%Y-%m-%d}.", *localtime(&t));

template<>
  struct formatter<tm> {
    constexpr format_parse_context::iterator parse(format_parse_context& ctx);

    template<class FormatContext>
      typename FormatContext::iterator format(const tm& tm, FormatContext& ctx);
  };

constexpr auto parse(type<T>, format_parse_context& ctx);

printf("String `%s' has %d characters\n", string, length(string)));

"%2$d Zeichen lang ist die Zeichenkette `%1$s'\n"

cout << "String `" << string << "' has " << length(string) << " characters\n";

format("String `{}' has {} characters\n", string, length(string)));

"{1} Zeichen lang ist die Zeichenkette `{0}'\n"

string vformat(string_view fmt, format_args args);

template<class... Args>
  inline string format(string_view fmt, const Args&... args) {
    return vformat(fmt, make_format_args(args...));
  }

template<class... Args>
  void log_error(int code, string_view fmt, const Args&... args) {
    clog << "Error " << code << ": " << format(fmt, args...);
  }

void vlog_error(int code, string_view fmt, format_args args) {
  clog << "Error " << code << ": " << vformat(fmt, args);
}

template<class... Args>
  inline void log_error(int code, string_view fmt, const Args&... args) {
    vlog_error(code, fmt, make_format_args(args...));
  }

using ci_string_view = std::basic_string_view<char, ci_char_traits>;
auto s = format(ci_string_view("{:X}"), 0xCAFE);

template<class String, class... Args>
  string format(String fmt, const Args&... args);

struct MyString {
  static constexpr string_view value() { return string_view("{}", 2); }
};

int width = 10;
int precision = 3;
auto s = format("{0:{1}.{2}f}", 12.345678, width, precision);
// s == "    12.346"

struct Answer {};

template<>
  struct formatter<Answer> {
    int width_arg_index = 0;

    // Parses dynamic width in the format "{<digit>}".
    auto parse(format_parse_context& parse_ctx) {
      auto iter = parse_ctx.begin();
      auto get_char = [&]() { return iter != parse_ctx.end() ? *iter : 0; };

      if (get_char() != '{')
        return iter;
      ++iter;
      char c = get_char();
      if (!std::isdigit(c) || (++iter, get_char()) != '}')
        throw format_error("invalid format");
      width_arg_index = c - '0';
      return ++iter;
    }

    auto format(Answer, format_context& format_ctx) {
      auto arg = format_ctx.arg(width_arg_index);
      int width = visit_format_arg([](auto value) -> int {
        if constexpr (!std::is_integral_v<decltype(value)>)
          throw format_error("width is not integral");
        else if (value < 0 || value > std::numeric_limits<int>::max())
          throw format_error("invalid width");
        else
          return value;
        }, arg);
      return format_to(format_ctx.out(), "{:{}}", 42, width);
    }
  };

std::string s = format("{0:{1}}", Answer(), 10);
// s == "        42"

Proposed wording

Editing notes

All wording is relative to the pre-Cologne C++ working draft N4820.

The � character is used to denote a placeholder section number, table number, or paragraph number which the editor shall determine.

Add the header <format> to the "C++ library headers" table in [headers], in a place that respects the table’s current alphabetic order.

Add an entry for __cpp_lib_format to the "Standard library feature-test macros" table in [support.limits.general], in a place that respects the table’s current alphabetic order:

Macro name	Value	Header(s)
…	…	…
__cpp_lib_format	201902L ** placeholder **	<format>
…	…	…

Add a new entry to the "General utilities library summary" table in [utilities.general]:

Subclause	Header(s)
…	…
20.19 Primitive numeric conversions	<charconv>
20.� Formatting	<format>

Add a new section in 20 [utilities].

20.� Formatting [format]

20.�.1 Header <format> synopsis [format.syn]

namespace std {
  // [format.error], class format_error
  class format_error;

  // [format.formatter], formatter
  template<class charT> class basic_format_parse_context;
  using format_parse_context = basic_format_parse_context<char>;
  using wformat_parse_context = basic_format_parse_context<wchar_t>;
  
  template<class Out, class charT> class basic_format_context;
  using format_context = basic_format_context<unspecified, char>;
  using wformat_context = basic_format_context<unspecified, wchar_t>;

  template<class T, class charT = char> struct formatter;
  
  // [format.arguments], arguments
  template<class Context> class basic_format_arg;

  template<class Visitor, class Context>
    see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);

  template<class Context, class... Args> struct format-arg-store; // exposition only

  template<class Context> class basic_format_args;
  using format_args = basic_format_args<format_context>;
  using wformat_args = basic_format_args<wformat_context>;

  template<class Out, class charT>
    using format_args_t = basic_format_args<basic_format_context<Out, charT>>;

  template<class Context = format_context, class... Args>
    format-arg-store<Context, Args...>
      make_format_args(const Args&... args);
  template<class... Args>
    format-arg-store<wformat_context, Args...>
      make_wformat_args(const Args&... args);

  // [format.functions], formatting functions
  template<class... Args>
    string format(string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(wstring_view fmt, const Args&... args);

  string vformat(string_view fmt, format_args args);
  wstring vformat(wstring_view fmt, wformat_args args);

  template<class Out, class... Args>
    Out format_to(Out out, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wstring_view fmt, const Args&... args);

  template<class Out>
    Out vformat_to(Out out, string_view fmt, format_args_t<Out, char> args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt, format_args_t<Out, wchar_t> args);

  template<class Out>
    struct format_to_n_result {
      Out out;
      iter_difference_t<Out> size;
    };
  
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        string_view fmt, const Args&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wstring_view fmt, const Args&... args);

  template<class... Args>
    size_t formatted_size(string_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(wstring_view fmt, const Args&... args);
}

20.�.2 Format string [format.string]

A format string is a (possibly empty) sequence of replacement fields, escape sequences, and other characters. Let charT be the character type of the format string. Each character that is not part of a replacement field or an escape sequence is copied unchanged to the output. An escape sequence is one of {{ or }}. It is replaced with { or } respectively in the output. The syntax of replacement fields is as follows:

replacement-field ::= '{' [arg-id] [':' format-spec] '}'
arg-id            ::= '0' | nonzero-digit [integer]
integer           ::= digit [integer]
nonzero-digit     ::= '1'...'9'
digit             ::= '0'...'9'

The arg-id field specifies the index of the argument in args whose value is to be formatted and inserted into the output instead of the replacement field. The optional format-spec field specifies a non-default format for the replacement value.

  string s = format("{0}-{{", 8); // s == "8-{"

If the numeric arg-ids 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 used in that order. A format string does not contain a mixture of automatic and manual indexing.

  string s0 = format("{} to {}",   "a", "b"); // OK: automatic indexing
  string s1 = format("{1} to {0}", "a", "b"); // OK: manual indexing
  string s2 = format("{0} to {}",  "a", "b"); // Error: mixing automatic and manual indexing
  string s3 = format("{} to {1}",  "a", "b"); // Error: mixing automatic and manual indexing

The format-spec field contains format specifications that define how the value should be presented, including such details as field width, alignment, padding, and decimal precision. Each type can define its own formatting mini-language or interpretation of the format-spec field. The syntax of format specifications is as follows:

format-spec     ::= std-format-spec | custom-format-spec
std-format-spec ::= [[fill] align] [sign] ['#'] ['0'] [width] ['.' precision] [type]
fill            ::= <a character other than '{' or '}'>
align           ::= '<' | '>' | '=' | '^'
sign            ::= '+' | '-' | ' '
width           ::= nonzero-digit [integer] | '{' arg-id '}'
precision       ::= integer | '{' arg-id '}'
type            ::= 'a' | 'A' | 'b' | 'B' | 'c' | 'd' | 'e' | 'E' | 'f' | 'F' |
                    'g' | 'G' | 'n' | 'o' | 'p' | 's' | 'x' | 'X'

where std-format-spec defines a common formatting mini-language supported by fundamental and string types, while custom-format-spec is a placeholder for user-defined mini-languages. Some of the formatting options are only supported for arithmetic types.

The fill character can be any character other than '{' or '}'. 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 std-format-spec is not a valid alignment option, then it is assumed that both the fill character and the alignment option are absent.

The meaning of the various alignment options is as follows:

[ Example:

  char c = 120;
  string s0 = format("{:6}", 42);      // s0 == "    42"
  string s1 = format("{:6}", 'x');     // s1 == "x     "
  string s2 = format("{:*<6}", 'x');   // s2 == "x*****"
  string s3 = format("{:*>6}", 'x');   // s3 == "*****x"
  string s4 = format("{:*^6}", 'x');   // s4 == "**x***"
  string s5 = format("{:=6}", 'x');    // Error: '=' with charT and no integer presentation type
  string s6 = format("{:6d}", c);      // s6 == "   120"
  string s7 = format("{:=+06d}", c);   // s7 == "+00120"
  string s8 = format("{:0=#6x}", 0xa); // s8 == "0x000a"
  string s9 = format("{:6}", true);    // s9 == "true  "

Unless a minimum field width is defined, the field width will be determined by the size of the content and the alignment option will have no effect.

The sign option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified. It can be one of the following:

The sign option applies to floating-point infinity and NaN.

  double inf = numeric_limits<double>::infinity();
  double nan = numeric_limits<double>::quiet_NaN();
  string s0 = format("{0:} {0:+} {0:-} {0: }", 1);   // s0 == "1 +1 1  1"
  string s1 = format("{0:} {0:+} {0:-} {0: }", -1);  // s1 == "-1 -1 -1 -1"
  string s2 = format("{0:} {0:+} {0:-} {0: }", inf); // s2 == "inf +inf inf  inf"
  string s3 = format("{0:} {0:+} {0:-} {0: }", nan); // s3 == "nan +nan nan  nan"

The '#' option causes the alternate form to be used for the conversion. This option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified. For integers, when binary, octal, or hexadecimal output is used, this option adds the respective prefix "0b" ("0B"), "0", or "0x" ("0X") to the output value. Whether the prefix is lower-case or upper-case is determined by the case of the type format specifier. 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 'g' and 'G' conversions, trailing zeros are not removed from the result.

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

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

The precision field is a decimal integer defining the precision or maximum field size. It can only be used with floating-point and string types. For floating-point types this field specifies the formatting precision. For string types it specifies how many characters will be used from the string.

Finally, the type determines how the data should be presented.

The available string presentation types are:

The available charT presentation types are:

Formatting of objects of arithmetic types and const void* is done as if by calling to_chars unless specified otherwise and copying the output through the output iterator of the format context with additional padding and adjustments as per format specifiers.

Let [first, last) be a range large enough to hold the to_chars output and value be the formatting argument value.

The available integer presentation types and their mapping to to_chars are:

Integer presentation types can also be used with charT and bool values. Values of type bool are formatted using textual representation, either "true" or "false", if the presentation type is not specified.

  string s0 = format("{}", 42);                      // s0 == "42"
  string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // s1 == "101010 42 52 2a"
  string s2 = format("{0:#x} {0:#X}", 42);           // s2 == "0x2a 0X2A"
  string s3 = format("{:n}", 1234);                  // s3 == "1,234" (depends on the locale)

The available floating-point presentation types and their mapping to to_chars (for values other than infinity and NaN) are:

For lower-case presentation types, infinity and NaN are formatted as "inf" and "nan", respectively, with sign, if any. For upper-case presentation types, infinity and NaN are formatted as "INF" and "NAN", respectively, with sign, if any.

The available pointer presentation types and their mapping to to_chars are:

[ Note: Pointer presentation types also apply to nullptr_t. — end note ]

20.�.3 Formatting functions [format.functions]

In the description of the functions, operator + is used for some of the iterator categories for which it does not have to be defined. In these cases the semantics of a + n are the same as in [algorithm.requirements].

template<class... Args> string format(string_view fmt, const Args&... args);

Effects: Equivalent to: return vformat(fmt, make_format_args(args...));

template<class... Args> wstring format(wstring_view fmt, const Args&... args);

Effects: Equivalent to: return vformat(fmt, make_wformat_args(args...));

string vformat(string_view fmt, format_args args); wstring vformat(wstring_view fmt, wformat_args args);

Returns: A string object holding the character representation of formatting arguments provided by args formatted according to specifications given in fmt.

Throws: format_error if fmt is not a format string.

template<class Out, class... Args> Out format_to(Out out, string_view fmt, const Args&... args); template<class Out, class... Args> Out format_to(Out out, wstring_view fmt, const Args&... args);

Effects: Equivalent to:

using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, fmt, {make_format_args<context>(args...)});

template<class Out> Out vformat_to(Out out, string_view fmt, format_args_t<Out, char> args); template<class Out> Out vformat_to(Out out, wstring_view fmt, format_args_t<Out, wchar_t> args);

Let charT be decltype(fmt)::value_type.

Constraints: Out satisfies OutputIterator<const charT&>.

Expects: Out models OutputIterator<const charT&>.

Effects: Places the character representation of formatting arguments provided by args, formatted according to specifications given in fmt, into the range [out, out + N), where N = formatted_size(fmt, args...).

Returns: out + N.

Throws: format_error if fmt is not a format string.

template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, string_view fmt, const Args&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, wstring_view fmt, const Args&... args);

Let charT be decltype(fmt)::value_type, N = formatted_size(fmt, args...), and M = min(max(n, 0), N).

Constraints: Out satisfies OutputIterator<const charT&>.

Expects: Out models OutputIterator<const charT&>, and formatter<T_i, charT> meets the Formatter requirements for each T_i in Args.

Effects: Places the first M characters of the character representation of formatting arguments provided by args, formatted according to specifications given in fmt, into the range [out, out + M).

Returns: {out + M, N}.

Throws: format_error if fmt is not a format string.

template<class... Args> size_t formatted_size(string_view fmt, const Args&... args); template<class... Args> size_t formatted_size(wstring_view fmt, const Args&... args);

Let charT be decltype(fmt)::value_type.

Expects: formatter<T_i, charT> meets the Formatter requirements for each T_i in Args.

Returns: The number of characters in the character representation of formatting arguments args formatted according to specifications given in fmt.

Throws: format_error if fmt is not a format string.

20.�.4 Formatter [format.formatter]

The functions defined in [format.functions] use specializations of the class template formatter to format individual arguments.

Let charT be either char or wchar_t. Each specialization of formatter is either enabled or disabled, as described below. [ Note: Enabled specializations meet the Formatter requirements, and disabled specializations do not. — end note ] Each header that declares the template formatter provides enabled specializations:

• template<> struct formatter<charT, charT>;

• template<> struct formatter<char, wchar_t>;

• template<> struct formatter<charT*, charT>;

• template<> struct formatter<const charT*, charT>;

• template<size_t N> struct formatter<const charT[N], charT>;

• template<class traits, class Allocator>
    struct formatter<basic_string<charT, traits, Allocator>, charT>;

• template<class traits>
    struct formatter<basic_string_view<charT, traits>, charT>;

• specializations of formatter for nullptr_t, void*, const void*, bool, and all cv-unqualified standard integer types, extended integer types, and floating-point types as the first template argument and charT as the second template argument,

For any types T and charT for which neither the library nor the user provides an explicit or partial specialization of the class template formatter, formatter<T, charT> is disabled.

If the library provides an explicit or partial specialization of formatter<T, charT>, that specialization is enabled except as noted otherwise.

If F is a disabled specialization of formatter, these values are false: is_default_constructible_v<F>, is_copy_constructible_v<F>, is_move_constructible_v<F>, is_copy_assignable_v<F>, is_move_assignable_v<F>.

An enabled specialization formatter<T, charT> meets the Formatter requirements.

  #include <format>

  enum color { red, green, blue };

  const char* color_names[] = { "red", "green", "blue" };

  template<> struct std::formatter<color> : std::formatter<const char*> {
    auto format(color c, format_context& ctx) {
      return formatter<const char*>::format(color_names[c], ctx);
    }
  };

  struct err {};

  std::string s0 = std::format("{}", 42);     // OK: library-provided formatter
  std::string s1 = std::format("{}", L"foo"); // Ill-formed: disabled formatter
  std::string s2 = std::format("{}", red);    // OK: user-provided formatter
  std::string s3 = std::format("{}", err{});  // Ill-formed: disabled formatter

20.�.4.1 Formatter requirements [formatter.requirements]

A type F meets the Formatter requirements if:

• it meets the Cpp17DefaultConstructible (Table 25), Cpp17CopyConstructible (Table 27), Cpp17CopyAssignable (Table 29), and Cpp17Destructible (Table 30) requirements,
• it is swappable ([swappable.requirements]) for lvalues, and
• the expressions shown in Table � are valid and have the indicated semantics.

Given character type charT, output iterator type Out, and formatting argument type T, in Table � f is a value of type F, u is an lvalue of type T, t is a value of a type convertible to (possibly const) T, PC is basic_format_parse_context<charT>, FC is basic_format_context<Out, charT>, pc is an lvalue of type PC, and fc is an lvalue of type FC. pc.begin() points to the beginning of the format-spec ([format.syntax]) portion of the format string. If format-spec is empty then either pc.begin() == pc.end() or *pc.begin() == '}'.

20.�.4.2 Class template basic_format_parse_context [format.parse_context]

namespace std {
  template<class charT>
  class basic_format_parse_context {
  public:
    using char_type = charT;
    using const_iterator = typename basic_string_view<charT>::const_iterator;
    using iterator = const_iterator;

  private:
    iterator begin_;                              // exposition only
    iterator end_;                                // exposition only
    enum indexing { unknown, manual, automatic }; // exposition only
    indexing indexing_;                           // exposition only
    size_t next_arg_id_;                          // exposition only
    size_t num_args_;                             // exposition only

  public:
    explicit constexpr basic_format_parse_context(basic_string_view<charT> fmt,
                                                  size_t num_args = 0) noexcept;
    basic_format_parse_context(const basic_format_parse_context&) = delete;
    basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;

    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr void advance_to(const_iterator it);

    constexpr size_t next_arg_id();
    constexpr void check_arg_id(size_t id);
  };
}

An instance of basic_format_parse_context holds the format string parsing state consisting of the format string range being parsed and the argument counter for automatic indexing.

explicit constexpr basic_format_parse_context(basic_string_view<charT> fmt, size_t num_args = 0) noexcept;

Effects: Initializes begin_ with fmt.begin(), end_ with fmt.end(), indexing_ with unknown, next_arg_id_ with 0, and num_args_ with num_args.

constexpr const_iterator begin() const noexcept;

Returns: begin_.

constexpr const_iterator end() const noexcept;

Returns: end_.

constexpr void advance_to(const_iterator it);

Expects: end() is reachable from it.

Effects: Equivalent to: begin_ = it;

constexpr size_t next_arg_id();

Effects: If indexing_ != manual, equivalent to:

  if (indexing_ == unknown)
    indexing_ = automatic;
  return next_arg_id_++;

Throws: format_error if indexing_ == manual which indicates mixing of automatic and manual argument indexing.

constexpr void check_arg_id(size_t id);

Effects: If indexing_ != automatic, equivalent to:

  if (indexing_ == unknown)
    indexing_ = manual;

Throws: format_error if indexing_ == automatic which indicates mixing of automatic and manual argument indexing.

Remarks: Call expressions where id >= num_args_ are not core constant expressions ([expr.const]).

20.�.4.3 Class template basic_format_context [format.context]

namespace std {
  template<class Out, class charT>
  class basic_format_context {
    basic_format_args<basic_format_context> args_; // exposition only
    Out out_;                                      // exposition only

  public:
    using iterator = Out;
    using char_type = charT;
    template<class T> using formatter_type = formatter<T, charT>;

    basic_format_arg<basic_format_context> arg(size_t id) const;

    iterator out();
    void advance_to(iterator it);
  };
}

An instance of basic_format_context holds formatting state consisting of the formatting arguments and the output iterator.

Out shall model OutputIterator<const charT&>.

format_context is an alias for the instantiation of basic_format_context with an output iterator that appends to string such as back_insert_iterator<string>.

[ Note: For a given type charT, implementations are encouraged to provide a single instantiation of basic_format_context for appending to basic_string<charT>, vector<charT>, or any other container with contiguous storage by wrapping those in temporary objects with uniform interface (like span) and polymorphic reallocation. — end note ]

basic_format_arg<basic_format_context> arg(size_t id) const;

Returns: args_.get(id).

iterator out();

Returns: out_.

void advance_to(iterator it);

Effects: Equivalent to: out_ = it;

  struct S {
    int value;
  };

  template<> struct std::formatter<S> {
    size_t width_arg_id = 0;

    // Parses a width argument id in the format { <digit> }.
    constexpr auto parse(format_parse_context& ctx) {
      auto iter = ctx.begin();
      auto get_char = [&]() { return iter != ctx.end() ? *iter : 0; };
      if (get_char() != '{')
        return iter;
      ++iter;
      char c = get_char();
      if (!isdigit(c) || (++iter, get_char()) != '}')
        throw format_error("invalid format");
      width_arg_id = c - '0';
      ctx.check_arg_id(width_arg_id);
      return ++iter;
    }

    // Formats S with width given by the argument width_arg_id.
    auto format(S s, format_context& ctx) {
      int width = visit_format_arg([](auto value) -> int {
        if constexpr (!is_integral_v<decltype(value)>)
          throw format_error("width is not integral");
        else if (value < 0 || value > numeric_limits<int>::max())
          throw format_error("invalid width");
        else
          return value;
        }, ctx.arg(width_arg_id));
      return format_to(ctx.out(), "{0:{1}}", s.value, width);
    }
  };

  std::string s = std::format("{0:{1}}", S{42}, 10); // s == "        42"

20.�.5 Arguments [format.arguments]

20.�.5.1 Class template basic_format_arg [format.arg]

namespace std {
  template<class Context>
  class basic_format_arg {
  public:
    class handle;

  private:
    using char-type = typename Context::char_type;                       // exposition only

    variant<monostate, bool, char-type,
            int, unsigned int, long long int, unsigned long long int,
            double, long double,
            const char-type*, basic_string_view<char-type>,
            const void*, handle> value;                                  // exposition only

    template<typename T> explicit basic_format_arg(const T& v) noexcept; // exposition only
    explicit basic_format_arg(float n) noexcept;                         // exposition only
    explicit basic_format_arg(double n) noexcept;                        // exposition only
    explicit basic_format_arg(long double n) noexcept;                   // exposition only
    explicit basic_format_arg(const char-type* s);                       // exposition only

    template<class traits>
      explicit basic_format_arg(
        basic_string_view<char-type, traits> s) noexcept;                // exposition only

    template<class traits, class Allocator>
      explicit basic_format_arg(
        const basic_string<char-type, traits, Allocator>& s) noexcept;   // exposition only

    explicit basic_format_arg(nullptr_t) noexcept;                       // exposition only

    template<class T>
      explicit basic_format_arg(const T* p) noexcept;                    // exposition only

    template<class Visitor, class Ctx>
      friend auto visit_format_arg(Visitor&& vis,
                                   basic_format_arg<Ctx> arg);           // exposition only

    template<class Ctx, class... Args>
      friend format-arg-store<Ctx, Args...>
        make_format_args(const Args&... args);                           // exposition only

  public:
    basic_format_arg() noexcept;

    explicit operator bool() const noexcept;
  };
}

An instance of basic_format_arg provides access to a formatting argument for user-defined formatters.

The behavior of a program that adds specializations of basic_format_arg is undefined.

basic_format_arg() noexcept;

Ensures: !(*this).

template<class T> explicit basic_format_arg(const T& v) noexcept;

Constraints: typename Context::template formatter_type<T> is enabled. The extent to which an implementation determines that typename Context::template formatter_type<T> is enabled is unspecified, except that as a minimum the expression typename Context::template formatter_type<T>().format(declval<const T&>(), declval<Context&>()) shall be well-formed when treated as an unevaluated operand.

Effects:

• if T is bool or char-type, initializes value with v; otherwise,
• if T is char and char-type is wchar_t, initializes value with static_cast<wchar_t>(v); otherwise,
• if T is a signed integer type ([basic.fundamental]) and sizeof(T) <= sizeof(int), initializes value with static_cast<int>(v); otherwise,
• if T is an unsigned integer type and sizeof(T) <= sizeof(unsigned int), initializes value with static_cast<unsigned int>(v); otherwise,
• if T is a signed integer type and sizeof(T) <= sizeof(long long int), initializes value with static_cast<long long int>(v); otherwise,
• if T is an unsigned integer type and sizeof(T) <= sizeof(unsigned long long int), initializes value with static_cast<unsigned long long int>(v); otherwise,
• initializes value with handle(v).

explicit basic_format_arg(float n) noexcept;

Effects: Initializes value with static_cast<double>(n).

explicit basic_format_arg(double n) noexcept;
explicit basic_format_arg(long double n) noexcept;

Effects: Initializes value with n.

explicit basic_format_arg(const char-type* s);

Expects: s points to a NTCTS ([defns.ntcts]).

Effects: Initializes value with s.

template<class traits> explicit basic_format_arg(basic_string_view<char-type, traits> s) noexcept;

Effects: Initializes value with s.

template<class traits, class Allocator> explicit basic_format_arg( const basic_string<char-type, traits, Allocator>& s) noexcept;

Effects: Initializes value with basic_string_view<char-type>(s.data(), s.size()).

explicit basic_format_arg(nullptr_t) noexcept;

Effects: Initializes value with static_cast<const void*>(nullptr).

template<class T> explicit basic_format_arg(T* p) noexcept;

Constraints: is_void_v<T> is true.

Effects: Initializes value with p.

[ Note: Constructing basic_format_arg from a pointer to a member is ill-formed unless the user provides an enabled specialization of formatter for this pointer to member type. — end note ]

explicit operator bool() const noexcept;

Returns: !holds_alternative<monostate>(value).

The class handle allows formatting an object of a user-defined type.

namespace std {
  template<class Context>
  class basic_format_arg<Context>::handle {
    const void* ptr_;                                         // exposition only
    void (*format_)(basic_format_parse_context<char-type>&,
                    Context&, const void*);                   // exposition only

    template<class T> explicit handle(const T& val) noexcept; // exposition only

    friend class basic_format_arg<Context>;                   // exposition only

  public:
    void format(basic_format_parse_context<char-type>&, Context& ctx) const;
  };
}

template<class T> explicit handle(const T& val) noexcept;

Effects: Initializes ptr_ with addressof(val) and format_ with

[](basic_format_parse_context<char-type>& parse_ctx, Context& format_ctx, const void* ptr) {
    typename Context::template formatter_type<T> f;
    parse_ctx.advance_to(f.parse(parse_ctx));
    format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx));
  }

void format(basic_format_parse_context<char-type>& parse_ctx, Context& format_ctx) const;

Effects: Equivalent to: format_(parse_ctx, format_ctx, ptr_);

20.�.5.2 Argument visitation [format.visit]

template<class Visitor, class Context> see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);

Effects: Equivalent to: return visit(forward<Visitor>(vis), arg.value);

20.�.5.3 Class template format-arg-store [format.arg_store]

namespace std {
  template<class Context, class... Args>
  struct format-arg-store { // exposition only
    array<basic_format_arg<Context>, sizeof...(Args)> args;
  };
}

An instance of format-arg-store stores formatting arguments.

20.�.5.4 Function template make_format_args [format.make_args]

template<class Context = format_context, class... Args> format-arg-store<Context, Args...> make_format_args(const Args&... args);

Expects: typename Context::template formatter_type<Ti> meets the Formatter requirements for each T_i in Args.

Returns: {basic_format_arg<Context>(args)...}.

20.�.5.5 Function template make_wformat_args [format.make_wargs]

template<class... Args> format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... args);

Effects: Equivalent to: return make_format_args<wformat_context>(args...);

20.�.5.6 Class template basic_format_args [format.basic_args]

namespace std {
  template<class Context>
  class basic_format_args {
    size_t size_;                           // exposition only
    const basic_format_arg<Context>* data_; // exposition only

  public:
    basic_format_args() noexcept;

    template<class... Args>
      basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;

    basic_format_arg<Context> get(size_t i) const noexcept;
  };
}

An instance of basic_format_args provides access to formatting arguments.

basic_format_args() noexcept;

Effects: Initializes size_ with 0.

template<class... Args> basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;

Effects: Initializes size_ with sizeof...(Args) and data_ with store.args.data().

basic_format_arg<Context> get(size_t i) const noexcept;

Returns: i < size_ ? data_[i] : basic_format_arg<Context>().

20.�.6 Class format_error [format.error]

namespace std {
  class format_error : public runtime_error {
  public:
    explicit format_error(const string& what_arg);
    explicit format_error(const char* what_arg);
  };
}

The class format_error defines the type of objects thrown as exceptions to report errors from the formatting library.

format_error(const string& what_arg);

Ensures: strcmp(what(), what_arg.c_str()) == 0.

format_error(const char* what_arg);

Ensures: strcmp(what(), what_arg) == 0.

  #include <algorithm>
  #include <cmath>
  #include <cstdio>
  #include <limits>
  #include <sstream>
  #include <string>
  #include <utility>
  #include <vector>

  #include <benchmark/benchmark.h>
  #include <fmt/format.h>

  // Returns a pair with the smallest and the largest value of integral type T
  // with the given number of digits.
  template<typename T>
  std::pair<T, T> range(int num_digits) {
    T first = std::pow(T(10), num_digits - 1);
    int max_digits = std::numeric_limits<T>::digits10 + 1;
    T last = num_digits < max_digits ? first * 10 - 1 :
                                 std::numeric_limits<T>::max();
    return {num_digits > 1 ? first : 0, last};
  }

  // Generates values of integral type T with random number of digits.
  template<typename T>
  std::vector<T> generate_random_data(int numbers_per_digit) {
    int max_digits = std::numeric_limits<T>::digits10 + 1;
    std::vector<T> data;
    data.reserve(max_digits * numbers_per_digit);
    for (int i = 1; i <= max_digits; ++i) {
      auto r = range<T>(i);
      auto value = r.first;
      std::generate_n(std::back_inserter(data), numbers_per_digit, [=]() mutable {
        T result = value;
        value = value < r.second ? value + 1 : r.first;
        return result;
      });
    }
    std::random_shuffle(data.begin(), data.end());
    return data;
  }

  auto data = generate_random_data<int>(1000);

  void sprintf(benchmark::State& s) {
    size_t result = 0;
    while (s.KeepRunning()) {
      for (auto i: data) {
        char buffer[12];
        result += std::sprintf(buffer, "%d", i);
      }
    }
    benchmark::DoNotOptimize(result);
  }
  BENCHMARK(sprintf);

  void ostringstream(benchmark::State& s) {
    size_t result = 0;
    while (s.KeepRunning()) {
      for (auto i: data) {
        std::ostringstream ss;
        ss << i;
        result += ss.str().size();
      }
    }
    benchmark::DoNotOptimize(result);
  }
  BENCHMARK(ostringstream);

  void to_string(benchmark::State& s) {
    size_t result = 0;
    while (s.KeepRunning()) {
      for (auto i: data)
        result += std::to_string(i).size();
    }
    benchmark::DoNotOptimize(result);
  }
  BENCHMARK(to_string);

  void format(benchmark::State& s) {
    size_t result = 0;
    while (s.KeepRunning()) {
      for (auto i: data)
        result += fmt::format("{}", i).size();
    }
    benchmark::DoNotOptimize(result);
  }
  BENCHMARK(format);

  void format_to(benchmark::State& s) {
    size_t result = 0;
    while (s.KeepRunning()) {
      for (auto i: data) {
        char buffer[12];
        result += fmt::format_to(buffer, "{}", i) - buffer;
      }
    }
    benchmark::DoNotOptimize(result);
  }
  BENCHMARK(format_to);

  BENCHMARK_MAIN();

  Run on (4 X 3100 MHz CPU s)
  2018-01-27 07:12:00
  Benchmark              Time           CPU Iterations
  ----------------------------------------------------
  sprintf           882311 ns     881076 ns        781
  ostringstream    2892035 ns    2888975 ns        242
  to_string        1167422 ns    1166831 ns        610
  format            675636 ns     674382 ns       1045
  format_to         499376 ns     498996 ns       1263

  void consume(const char*);

  void sprintf_test() {
    char buffer[100];
    sprintf(buffer, "The answer is %d.", 42);
    consume(buffer);
  }

  __Z12sprintf_testv:
         0:       55      pushq   %rbp
         1:       48 89 e5        movq    %rsp, %rbp
         4:       53      pushq   %rbx
         5:       48 83 ec 78     subq    $120, %rsp
         9:       48 8b 05 00 00 00 00    movq    (%rip), %rax
        10:       48 8b 00        movq    (%rax), %rax
        13:       48 89 45 f0     movq    %rax, -16(%rbp)
        17:       48 8d 35 37 00 00 00    leaq    55(%rip), %rsi
        1e:       48 8d 5d 80     leaq    -128(%rbp), %rbx
        22:       ba 2a 00 00 00  movl    $42, %edx
        27:       31 c0   xorl    %eax, %eax
        29:       48 89 df        movq    %rbx, %rdi
        2c:       e8 00 00 00 00  callq   0 <__Z12sprintf_testv+0x31>
        31:       48 89 df        movq    %rbx, %rdi
        34:       e8 00 00 00 00  callq   0 <__Z12sprintf_testv+0x39>
        39:       48 8b 05 00 00 00 00    movq    (%rip), %rax
        40:       48 8b 00        movq    (%rax), %rax
        43:       48 3b 45 f0     cmpq    -16(%rbp), %rax
        47:       75 07   jne     7 <__Z12sprintf_testv+0x50>
        49:       48 83 c4 78     addq    $120, %rsp
        4d:       5b      popq    %rbx
        4e:       5d      popq    %rbp
        4f:       c3      retq
        50:       e8 00 00 00 00  callq   0 <__Z12sprintf_testv+0x55>

  void format_test() {
    consume(format("The answer is {}.", 42).c_str());
  }

  __Z11format_testv:
         0:       55      pushq   %rbp
         1:       48 89 e5        movq    %rsp, %rbp
         4:       53      pushq   %rbx
         5:       48 83 ec 28     subq    $40, %rsp
         9:       48 c7 45 d0 2a 00 00 00         movq    $42, -48(%rbp)
        11:       48 8d 35 f4 83 01 00    leaq    99316(%rip), %rsi
        18:       48 8d 7d e0     leaq    -32(%rbp), %rdi
        1c:       4c 8d 45 d0     leaq    -48(%rbp), %r8
        20:       ba 11 00 00 00  movl    $17, %edx
        25:       b9 02 00 00 00  movl    $2, %ecx
        2a:       e8 00 00 00 00  callq   0 <__Z11format_testv+0x2F>
        2f:       f6 45 e0 01     testb   $1, -32(%rbp)
        33:       48 8d 7d e1     leaq    -31(%rbp), %rdi
        37:       48 0f 45 7d f0  cmovneq -16(%rbp), %rdi
        3c:       e8 00 00 00 00  callq   0 <__Z11format_testv+0x41>
        41:       f6 45 e0 01     testb   $1, -32(%rbp)
        45:       74 09   je      9 <__Z11format_testv+0x50>
        47:       48 8b 7d f0     movq    -16(%rbp), %rdi
        4b:       e8 00 00 00 00  callq   0 <__Z11format_testv+0x50>
        50:       48 83 c4 28     addq    $40, %rsp
        54:       5b      popq    %rbx
        55:       5d      popq    %rbp
        56:       c3      retq
        57:       48 89 c3        movq    %rax, %rbx
        5a:       f6 45 e0 01     testb   $1, -32(%rbp)
        5e:       74 09   je      9 <__Z11format_testv+0x69>
        60:       48 8b 7d f0     movq    -16(%rbp), %rdi
        64:       e8 00 00 00 00  callq   0 <__Z11format_testv+0x69>
        69:       48 89 df        movq    %rbx, %rdi
        6c:       e8 00 00 00 00  callq   0 <__Z11format_testv+0x71>
        71:       66 66 66 66 66 66 2e 0f 1f 84 00 00 00 00 00    nopw    %cs:(%rax,%rax)

  void ostringstream_test() {
    std::ostringstream ss;
    ss << "The answer is " << 42 << ".";
    consume(ss.str().c_str());
  }

  __Z18ostringstream_testv:
         0:	55 	pushq	%rbp
         1:	48 89 e5 	movq	%rsp, %rbp
         4:	41 57 	pushq	%r15
         6:	41 56 	pushq	%r14
         8:	41 55 	pushq	%r13
         a:	41 54 	pushq	%r12
         c:	53 	pushq	%rbx
         d:	48 81 ec 38 01 00 00 	subq	$312, %rsp
        14:	4c 8d b5 18 ff ff ff 	leaq	-232(%rbp), %r14
        1b:	4c 8d a5 b0 fe ff ff 	leaq	-336(%rbp), %r12
        22:	48 8b 05 00 00 00 00 	movq	(%rip), %rax
        29:	48 8d 48 18 	leaq	24(%rax), %rcx
        2d:	48 89 8d a8 fe ff ff 	movq	%rcx, -344(%rbp)
        34:	48 83 c0 40 	addq	$64, %rax
        38:	48 89 85 18 ff ff ff 	movq	%rax, -232(%rbp)
        3f:	4c 89 f7 	movq	%r14, %rdi
        42:	4c 89 e6 	movq	%r12, %rsi
        45:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x4A>
        4a:	48 c7 45 a0 00 00 00 00 	movq	$0, -96(%rbp)
        52:	c7 45 a8 ff ff ff ff 	movl	$4294967295, -88(%rbp)
        59:	48 8b 1d 00 00 00 00 	movq	(%rip), %rbx
        60:	4c 8d 6b 18 	leaq	24(%rbx), %r13
        64:	4c 89 ad a8 fe ff ff 	movq	%r13, -344(%rbp)
        6b:	48 83 c3 40 	addq	$64, %rbx
        6f:	48 89 9d 18 ff ff ff 	movq	%rbx, -232(%rbp)
        76:	4c 89 e7 	movq	%r12, %rdi
        79:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x7E>
        7e:	4c 8b 3d 00 00 00 00 	movq	(%rip), %r15
        85:	49 83 c7 10 	addq	$16, %r15
        89:	4c 89 bd b0 fe ff ff 	movq	%r15, -336(%rbp)
        90:	48 c7 85 08 ff ff ff 00 00 00 00 	movq	$0, -248(%rbp)
        9b:	48 c7 85 00 ff ff ff 00 00 00 00 	movq	$0, -256(%rbp)
        a6:	48 c7 85 f8 fe ff ff 00 00 00 00 	movq	$0, -264(%rbp)
        b1:	48 c7 85 f0 fe ff ff 00 00 00 00 	movq	$0, -272(%rbp)
        bc:	c7 85 10 ff ff ff 10 00 00 00 	movl	$16, -240(%rbp)
        c6:	0f 57 c0 	xorps	%xmm0, %xmm0
        c9:	0f 29 45 b0 	movaps	%xmm0, -80(%rbp)
        cd:	48 c7 45 c0 00 00 00 00 	movq	$0, -64(%rbp)
        d5:	48 8d 75 b0 	leaq	-80(%rbp), %rsi
        d9:	4c 89 e7 	movq	%r12, %rdi
        dc:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0xE1>
        e1:	f6 45 b0 01 	testb	$1, -80(%rbp)
        e5:	74 09 	je	9 <__Z18ostringstream_testv+0xF0>
        e7:	48 8b 7d c0 	movq	-64(%rbp), %rdi
        eb:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0xF0>
        f0:	48 8d 35 dd 10 00 00 	leaq	4317(%rip), %rsi
        f7:	48 8d bd a8 fe ff ff 	leaq	-344(%rbp), %rdi
        fe:	ba 0e 00 00 00 	movl	$14, %edx
       103:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x108>
       108:	be 2a 00 00 00 	movl	$42, %esi
       10d:	48 89 c7 	movq	%rax, %rdi
       110:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x115>
       115:	48 8d 35 c7 10 00 00 	leaq	4295(%rip), %rsi
       11c:	ba 01 00 00 00 	movl	$1, %edx
       121:	48 89 c7 	movq	%rax, %rdi
       124:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x129>
       129:	48 8d 7d b0 	leaq	-80(%rbp), %rdi
       12d:	4c 89 e6 	movq	%r12, %rsi
       130:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x135>
       135:	f6 45 b0 01 	testb	$1, -80(%rbp)
       139:	48 8d 7d b1 	leaq	-79(%rbp), %rdi
       13d:	48 0f 45 7d c0 	cmovneq	-64(%rbp), %rdi
       142:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x147>
       147:	f6 45 b0 01 	testb	$1, -80(%rbp)
       14b:	74 09 	je	9 <__Z18ostringstream_testv+0x156>
       14d:	48 8b 7d c0 	movq	-64(%rbp), %rdi
       151:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x156>
       156:	4c 89 ad a8 fe ff ff 	movq	%r13, -344(%rbp)
       15d:	48 89 9d 18 ff ff ff 	movq	%rbx, -232(%rbp)
       164:	4c 89 bd b0 fe ff ff 	movq	%r15, -336(%rbp)
       16b:	f6 85 f0 fe ff ff 01 	testb	$1, -272(%rbp)
       172:	74 0c 	je	12 <__Z18ostringstream_testv+0x180>
       174:	48 8b bd 00 ff ff ff 	movq	-256(%rbp), %rdi
       17b:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x180>
       180:	4c 89 e7 	movq	%r12, %rdi
       183:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x188>
       188:	48 8b 35 00 00 00 00 	movq	(%rip), %rsi
       18f:	48 83 c6 08 	addq	$8, %rsi
       193:	48 8d bd a8 fe ff ff 	leaq	-344(%rbp), %rdi
       19a:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x19F>
       19f:	4c 89 f7 	movq	%r14, %rdi
       1a2:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x1A7>
       1a7:	48 81 c4 38 01 00 00 	addq	$312, %rsp
       1ae:	5b 	popq	%rbx
       1af:	41 5c 	popq	%r12
       1b1:	41 5d 	popq	%r13
       1b3:	41 5e 	popq	%r14
       1b5:	41 5f 	popq	%r15
       1b7:	5d 	popq	%rbp
       1b8:	c3 	retq
       1b9:	48 89 45 d0 	movq	%rax, -48(%rbp)
       1bd:	f6 45 b0 01 	testb	$1, -80(%rbp)
       1c1:	74 3b 	je	59 <__Z18ostringstream_testv+0x1FE>
       1c3:	48 8b 7d c0 	movq	-64(%rbp), %rdi
       1c7:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x1CC>
       1cc:	eb 30 	jmp	48 <__Z18ostringstream_testv+0x1FE>
       1ce:	eb 2a 	jmp	42 <__Z18ostringstream_testv+0x1FA>
       1d0:	48 89 45 d0 	movq	%rax, -48(%rbp)
       1d4:	f6 45 b0 01 	testb	$1, -80(%rbp)
       1d8:	74 39 	je	57 <__Z18ostringstream_testv+0x213>
       1da:	48 8b 7d c0 	movq	-64(%rbp), %rdi
       1de:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x1E3>
       1e3:	f6 85 f0 fe ff ff 01 	testb	$1, -272(%rbp)
       1ea:	75 30 	jne	48 <__Z18ostringstream_testv+0x21C>
       1ec:	eb 3a 	jmp	58 <__Z18ostringstream_testv+0x228>
       1ee:	48 89 45 d0 	movq	%rax, -48(%rbp)
       1f2:	eb 3c 	jmp	60 <__Z18ostringstream_testv+0x230>
       1f4:	48 89 45 d0 	movq	%rax, -48(%rbp)
       1f8:	eb 4d 	jmp	77 <__Z18ostringstream_testv+0x247>
       1fa:	48 89 45 d0 	movq	%rax, -48(%rbp)
       1fe:	4c 89 ad a8 fe ff ff 	movq	%r13, -344(%rbp)
       205:	48 89 9d 18 ff ff ff 	movq	%rbx, -232(%rbp)
       20c:	4c 89 bd b0 fe ff ff 	movq	%r15, -336(%rbp)
       213:	f6 85 f0 fe ff ff 01 	testb	$1, -272(%rbp)
       21a:	74 0c 	je	12 <__Z18ostringstream_testv+0x228>
       21c:	48 8b bd 00 ff ff ff 	movq	-256(%rbp), %rdi
       223:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x228>
       228:	4c 89 e7 	movq	%r12, %rdi
       22b:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x230>
       230:	48 8b 35 00 00 00 00 	movq	(%rip), %rsi
       237:	48 83 c6 08 	addq	$8, %rsi
       23b:	48 8d bd a8 fe ff ff 	leaq	-344(%rbp), %rdi
       242:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x247>
       247:	4c 89 f7 	movq	%r14, %rdi
       24a:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x24F>
       24f:	48 8b 7d d0 	movq	-48(%rbp), %rdi
       253:	e8 00 00 00 00 	callq	0 <__Z18ostringstream_testv+0x258>
       258:	0f 1f 84 00 00 00 00 00 	nopl	(%rax,%rax)

int vraw_format(char* buffer, const char* format, format_args args);

template<typename... Args>
inline int raw_format(char* buffer, const char* format, const Args&... args) {
  return vraw_format(buffer, format, make_format_args(args...));
}

void raw_format_test() {
  char buffer[100];
  raw_format(buffer, "The answer is {}.", 42);
}

__Z15raw_format_testv:
       0:       55      pushq   %rbp
       1:       48 89 e5        movq    %rsp, %rbp
       4:       48 81 ec 80 00 00 00    subq    $128, %rsp
       b:       48 8b 05 00 00 00 00    movq    (%rip), %rax
      12:       48 8b 00        movq    (%rax), %rax
      15:       48 89 45 f8     movq    %rax, -8(%rbp)
      19:       48 c7 45 80 2a 00 00 00         movq    $42, -128(%rbp)
      21:       48 8d 35 24 12 00 00    leaq    4644(%rip), %rsi
      28:       48 8d 7d 90     leaq    -112(%rbp), %rdi
      2c:       48 8d 4d 80     leaq    -128(%rbp), %rcx
      30:       ba 02 00 00 00  movl    $2, %edx
      35:       e8 00 00 00 00  callq   0 <__Z15raw_format_testv+0x3A>
      3a:       48 8b 05 00 00 00 00    movq    (%rip), %rax
      41:       48 8b 00        movq    (%rax), %rax
      44:       48 3b 45 f8     cmpq    -8(%rbp), %rax
      48:       75 09   jne     9 <__Z15raw_format_testv+0x53>
      4a:       48 81 c4 80 00 00 00    addq    $128, %rsp
      51:       5d      popq    %rbp
      52:       c3      retq
      53:       e8 00 00 00 00  callq   0 <__Z15raw_format_testv+0x58>
      58:       0f 1f 84 00 00 00 00 00         nopl    (%rax,%rax)