22 General utilities library [utilities]

22.14 Formatting [format]

22.14.1 Header <format> synopsis [format.syn]

namespace std { // [format.context], class template basic_­format_­context 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>; // [format.args], class template basic_­format_­args template<class Context> class basic_format_args; using format_args = basic_format_args<format_context>; using wformat_args = basic_format_args<wformat_context>; // [format.fmt.string], class template basic_­format_­string template<class charT, class... Args> struct basic_format_string; template<class... Args> using format_string = basic_format_string<char, type_identity_t<Args>...>; template<class... Args> using wformat_string = basic_format_string<wchar_t, type_identity_t<Args>...>; // [format.functions], formatting functions template<class... Args> string format(format_string<Args...> fmt, Args&&... args); template<class... Args> wstring format(wformat_string<Args...> fmt, Args&&... args); template<class... Args> string format(const locale& loc, format_string<Args...> fmt, Args&&... args); template<class... Args> wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args); string vformat(string_view fmt, format_args args); wstring vformat(wstring_view fmt, wformat_args args); string vformat(const locale& loc, string_view fmt, format_args args); wstring vformat(const locale& loc, wstring_view fmt, wformat_args args); template<class Out, class... Args> Out format_to(Out out, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args); template<class Out, class... Args> Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args); template<class Out> Out vformat_to(Out out, string_view fmt, format_args args); template<class Out> Out vformat_to(Out out, wstring_view fmt, wformat_args args); template<class Out> Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args); template<class Out> Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args 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, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, wformat_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, wformat_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(format_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(wformat_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args); // [format.formatter], formatter template<class T, class charT = char> struct formatter; // [format.formattable], concept formattable template<class T, class charT> concept formattable = see below; template<class R, class charT> concept const-formattable-range = // exposition only ranges::input_­range<const R> && formattable<ranges::range_reference_t<const R>, charT>; template<class R, class charT> using fmt-maybe-const = // exposition only conditional_t<const-formattable-range<R, charT>, const R, R>; // [format.parse.ctx], class template basic_­format_­parse_­context 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>; // [format.range], formatting of ranges // [format.range.fmtkind], variable template format_­kind enum class range_format { disabled, map, set, sequence, string, debug_string }; template<class R> constexpr unspecified format_kind = unspecified; template<ranges::input_­range R> requires same_­as<R, remove_cvref_t<R>> constexpr range_format format_kind<R> = see below; // [format.range.formatter], class template range_­formatter template<class T, class charT = char> requires same_­as<remove_cvref_t<T>, T> && formattable<T, charT> class range_formatter; // [format.range.fmtdef], class template range-default-formatter template<range_format K, ranges::input_­range R, class charT> struct range-default-formatter; // exposition only // [format.range.fmtmap], [format.range.fmtset], [format.range.fmtstr], specializations for maps, sets, and strings template<ranges::input_­range R, class charT> requires (format_kind<R> != range_format::disabled) && formattable<ranges::range_reference_t<R>, charT> struct formatter<R, charT> : range-default-formatter<format_kind<R>, R, charT> { }; // [format.arguments], arguments // [format.arg], class template basic_­format_­arg template<class Context> class basic_format_arg; template<class Visitor, class Context> decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg); // [format.arg.store], class template format-arg-store template<class Context, class... Args> class format-arg-store; // exposition only template<class Context = format_context, class... Args> format-arg-store<Context, Args...> make_format_args(Args&&... fmt_args); template<class... Args> format-arg-store<wformat_context, Args...> make_wformat_args(Args&&... args); // [format.error], class format_­error class format_error; }
The class template format_­to_­n_­result has the template parameters, data members, and special members specified above.
It has no base classes or members other than those specified.

22.14.2 Format string [format.string]

22.14.2.1 In general [format.string.general]

A format string for arguments args is a (possibly empty) sequence of replacement fields, escape sequences, and characters other than { and }.
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-specifier }
arg-id:
0
positive-integer
positive-integer:
nonzero-digit
positive-integer digit
nonnegative-integer:
digit
nonnegative-integer digit
nonzero-digit: one of
1 2 3 4 5 6 7 8 9
digit: one of
0 1 2 3 4 5 6 7 8 9
format-specifier:
: format-spec
format-spec:
as specified by the formatter specialization for the argument type
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.
If there is no argument with the index arg-id in args, the string is not a format string for args.
The optional format-specifier field explicitly specifies a format for the replacement value.
[Example 1: string s = format("{0}-{{", 8); // value of s is "8-{" — end example]
If all arg-ids in a format string are omitted (including those in the format-spec, as interpreted by the corresponding formatter specialization), argument indices 0, 1, 2, … will automatically be used in that order.
If some arg-ids are omitted and some are present, the string is not a format string.
[Note 1:
A format string cannot contain a mixture of automatic and manual indexing.
— end note]
[Example 2: 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"); // not a format string (mixing automatic and manual indexing), // ill-formed string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing), // ill-formed — end example]
The format-spec field contains format specifications that define how the value should be presented.
Each type can define its own interpretation of the format-spec field.
If format-spec does not conform to the format specifications for the argument type referred to by arg-id, the string is not a format string for args.
[Example 3:
  • For arithmetic, pointer, and string types the format-spec is interpreted as a std-format-spec as described in ([format.string.std]).
  • For chrono types the format-spec is interpreted as a chrono-format-spec as described in ([time.format]).
  • For user-defined formatter specializations, the behavior of the parse member function determines how the format-spec is interpreted.
— end example]

22.14.2.2 Standard format specifiers [format.string.std]

Each formatter specializations described in [format.formatter.spec] for fundamental and string types interprets format-spec as a std-format-spec.
[Note 1:
The format specification can be used to specify such details as field width, alignment, padding, and decimal precision.
Some of the formatting options are only supported for arithmetic types.
— end note]
The syntax of format specifications is as follows:
std-format-spec:
fill-and-align sign # 0 width precision L type
fill-and-align:
fill align
fill:
any character other than { or }
align: one of
< > ^
sign: one of
+ - space
width:
positive-integer
{ arg-id }
precision:
. nonnegative-integer
. { arg-id }
type: one of
a A b B c d e E f F g G o p s x X ?
[Note 2:
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.
— end note]
The align specifier applies to all argument types.
The meaning of the various alignment options is as specified in Table 66.
[Example 1: char c = 120; string s0 = format("{:6}", 42); // value of s0 is "    42" string s1 = format("{:6}", 'x'); // value of s1 is "x     " string s2 = format("{:*<6}", 'x'); // value of s2 is "x*****" string s3 = format("{:*>6}", 'x'); // value of s3 is "*****x" string s4 = format("{:*^6}", 'x'); // value of s4 is "**x***" string s5 = format("{:6d}", c); // value of s5 is "   120" string s6 = format("{:6}", true); // value of s6 is "true  " — end example]
[Note 3:
Unless a minimum field width is defined, the field width is determined by the size of the content and the alignment option has no effect.
— end note]
Table 66: Meaning of align options [tab:format.align]
Option
Meaning
<
Forces the field to be aligned to the start of the available space.
This is the default for non-arithmetic non-pointer types, charT, and bool, unless an integer presentation type is specified.
>
Forces the field to be aligned to the end of the available space.
This is the default for arithmetic types other than charT and bool, pointer types, or when an integer presentation type is specified.
^
Forces the field to be centered within the available space by inserting characters before and characters after the value, where n is the total number of fill characters to insert.
The sign option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified.
The meaning of the various options is as specified in Table 67.
Table 67: Meaning of sign options [tab:format.sign]
Option
Meaning
+
Indicates that a sign should be used for both non-negative and negative numbers.
The + sign is inserted before the output of to_­chars for non-negative numbers other than negative zero.
[Note 4:
For negative numbers and negative zero the output of to_­chars will already contain the sign so no additional transformation is performed.
— end note]
-
Indicates that a sign should be used for negative numbers and negative zero only (this is the default behavior).
space
Indicates that a leading space should be used for non-negative numbers other than negative zero, and a minus sign for negative numbers and negative zero.
The sign option applies to floating-point infinity and NaN.
[Example 2: double inf = numeric_limits<double>::infinity(); double nan = numeric_limits<double>::quiet_NaN(); string s0 = format("{0:},{0:+},{0:-},{0: }", 1); // value of s0 is "1,+1,1, 1" string s1 = format("{0:},{0:+},{0:-},{0: }", -1); // value of s1 is "-1,-1,-1,-1" string s2 = format("{0:},{0:+},{0:-},{0: }", inf); // value of s2 is "inf,+inf,inf, inf" string s3 = format("{0:},{0:+},{0:-},{0: }", nan); // value of s3 is "nan,+nan,nan, nan" — end example]
The # option causes the alternate form to be used for the conversion.
This option is valid for arithmetic types other than charT and bool or when an integer presentation type is specified, and not otherwise.
For integral types, the alternate form inserts the base prefix (if any) specified in Table 69 into the output after the sign character (possibly space) if there is one, or before the output of to_­chars otherwise.
For floating-point types, the alternate form causes the result of the conversion of finite values 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.
A zero (0) character preceding the width field pads the field with leading zeros (following any indication of sign or base) to the field width, except when applied to an infinity or NaN. This option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified.
If the 0 character and an align option both appear, the 0 character is ignored.
[Example 3: char c = 120; string s1 = format("{:+06d}", c); // value of s1 is "+00120" string s2 = format("{:#06x}", 0xa); // value of s2 is "0x000a" string s3 = format("{:<06}", -42); // value of s3 is "-42   " (0 is ignored because of < alignment) — end example]
If { arg-id } is used in a width or precision, the value of the corresponding formatting argument is used in its place.
If the corresponding formatting argument is not of integral type, or its value is negative, an exception of type format_­error is thrown.
The positive-integer in width is a decimal integer defining the minimum field width.
If width is not specified, there is no minimum field width, and the field width is determined based on the content of the field.
The width of a string is defined as the estimated number of column positions appropriate for displaying it in a terminal.
[Note 5:
This is similar to the semantics of the POSIX wcswidth function.
— end note]
For the purposes of width computation, a string is assumed to be in a locale-independent, implementation-defined encoding.
Implementations should use a Unicode encoding on platforms capable of displaying Unicode text in a terminal.
[Note 6:
This is the case for Windows209-based and many POSIX-based operating systems.
— end note]
For a string in a Unicode encoding, implementations should estimate the width of a string as the sum of estimated widths of the first code points in its extended grapheme clusters.
The extended grapheme clusters of a string are defined by UAX #29.
The estimated width of the following code points is 2: The estimated width of other code points is 1.
For a string in a non-Unicode encoding, the width of a string is unspecified.
The nonnegative-integer in precision 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, this field provides an upper bound for the estimated width of the prefix of the input string that is copied into the output.
For a string in a Unicode encoding, the formatter copies to the output the longest prefix of whole extended grapheme clusters whose estimated width is no greater than the precision.
When the L option is used, the form used for the conversion is called the locale-specific form.
The L option is only valid for arithmetic types, and its effect depends upon the type.
  • For integral types, the locale-specific form causes the context's locale to be used to insert the appropriate digit group separator characters.
  • For floating-point types, the locale-specific form causes the context's locale to be used to insert the appropriate digit group and radix separator characters.
  • For the textual representation of bool, the locale-specific form causes the context's locale to be used to insert the appropriate string as if obtained with numpunct​::​truename or numpunct​::​falsename.
The type determines how the data should be presented.
The available string presentation types are specified in Table 68.
Table 68: Meaning of type options for strings [tab:format.type.string]
Type
Meaning
none, s
Copies the string to the output.
?
Copies the escaped string ([format.string.escaped]) to the output.
The meaning of some non-string presentation types is defined in terms of a call to to_­chars.
In such cases, let [first, last) be a range large enough to hold the to_­chars output and value be the formatting argument value.
Formatting is done as if by calling to_­chars as specified and copying the output through the output iterator of the format context.
[Note 7:
Additional padding and adjustments are performed prior to copying the output through the output iterator as specified by the format specifiers.
— end note]
The available integer presentation types for integral types other than bool and charT are specified in Table 69.
[Example 4: string s0 = format("{}", 42); // value of s0 is "42" string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // value of s1 is "101010 42 52 2a" string s2 = format("{0:#x} {0:#X}", 42); // value of s2 is "0x2a 0X2A" string s3 = format("{:L}", 1234); // value of s3 can be "1,234" // (depending on the locale) — end example]
Table 69: Meaning of type options for integer types [tab:format.type.int]
Type
Meaning
b
to_­chars(first, last, value, 2); the base prefix is 0b.
B
The same as b, except that the base prefix is 0B.
c
Copies the character static_­cast<charT>(value) to the output.
Throws format_­error if value is not in the range of representable values for charT.
d
to_­chars(first, last, value).
o
to_­chars(first, last, value, 8); the base prefix is 0 if value is nonzero and is empty otherwise.
x
to_­chars(first, last, value, 16); the base prefix is 0x.
X
The same as x, except that it uses uppercase letters for digits above 9 and the base prefix is 0X.
none
The same as d.
[Note 8:
If the formatting argument type is charT or bool, the default is instead c or s, respectively.
— end note]
The available charT presentation types are specified in Table 70.
Table 70: Meaning of type options for charT[tab:format.type.char]
Type
Meaning
none, c
Copies the character to the output.
b, B, d, o, x, X
As specified in Table 69.
?
Copies the escaped character ([format.string.escaped]) to the output.
The available bool presentation types are specified in Table 71.
Table 71: Meaning of type options for bool[tab:format.type.bool]
Type
Meaning
none, s
Copies textual representation, either true or false, to the output.
b, B, d, o, x, X
As specified in Table 69 for the value static_­cast<unsigned char>(value).
The available floating-point presentation types and their meanings for values other than infinity and NaN are specified in Table 72.
For lower-case presentation types, infinity and NaN are formatted as inf and nan, respectively.
For upper-case presentation types, infinity and NaN are formatted as INF and NAN, respectively.
[Note 9:
In either case, a sign is included if indicated by the sign option.
— end note]
Table 72: Meaning of type options for floating-point types [tab:format.type.float]
Type
Meaning
a
If precision is specified, equivalent to to_chars(first, last, value, chars_format::hex, precision) where precision is the specified formatting precision; equivalent to to_chars(first, last, value, chars_format::hex) otherwise.
A
The same as a, except that it uses uppercase letters for digits above 9 and P to indicate the exponent.
e
Equivalent to to_chars(first, last, value, chars_format::scientific, precision) where precision is the specified formatting precision, or 6 if precision is not specified.
E
The same as e, except that it uses E to indicate exponent.
f, F
Equivalent to to_chars(first, last, value, chars_format::fixed, precision) where precision is the specified formatting precision, or 6 if precision is not specified.
g
Equivalent to to_chars(first, last, value, chars_format::general, precision) where precision is the specified formatting precision, or 6 if precision is not specified.
G
The same as g, except that it uses E to indicate exponent.
none
If precision is specified, equivalent to to_chars(first, last, value, chars_format::general, precision) where precision is the specified formatting precision; equivalent to to_chars(first, last, value) otherwise.
The available pointer presentation types and their mapping to to_­chars are specified in Table 73.
[Note 10:
Pointer presentation types also apply to nullptr_­t.
— end note]
Table 73: Meaning of type options for pointer types [tab:format.type.ptr]
Type
Meaning
none, p
If uintptr_­t is defined, to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) with the prefix 0x inserted immediately before the output of to_­chars; otherwise, implementation-defined.
209)209)
Windows® is a registered trademark of Microsoft Corporation.
This information is given for the convenience of users of this document and does not constitute an endorsement by ISO or IEC of this product.

22.14.3 Error reporting [format.err.report]

Formatting functions throw format_­error if an argument fmt is passed that is not a format string for args.
They propagate exceptions thrown by operations of formatter specializations and iterators.
Failure to allocate storage is reported by throwing an exception as described in [res.on.exception.handling].

22.14.4 Class template basic_­format_­string [format.fmt.string]

namespace std { template<class charT, class... Args> struct basic_format_string { private: basic_string_view<charT> str; // exposition only public: template<class T> consteval basic_format_string(const T& s); constexpr basic_string_view<charT> get() const noexcept { return str; } }; }
template<class T> consteval basic_format_string(const T& s);
Constraints: const T& models convertible_­to<basic_­string_­view<charT>>.
Effects: Direct-non-list-initializes str with s.
Remarks: A call to this function is not a core constant expression ([expr.const]) unless there exist args of types Args such that str is a format string for args.

22.14.5 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 [algorithms.requirements].
template<class... Args> string format(format_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat(fmt.str, make_format_args(args...));
template<class... Args> wstring format(wformat_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat(fmt.str, make_wformat_args(args...));
template<class... Args> string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat(loc, fmt.str, make_format_args(args...));
template<class... Args> wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat(loc, fmt.str, make_wformat_args(args...));
string vformat(string_view fmt, format_args args); wstring vformat(wstring_view fmt, wformat_args args); string vformat(const locale& loc, string_view fmt, format_args args); wstring vformat(const locale& loc, 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.
If present, loc is used for locale-specific formatting.
Throws: As specified in [format.err.report].
template<class Out, class... Args> Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat_to(std::move(out), fmt.str, make_format_args(args...));
template<class Out, class... Args> Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat_to(std::move(out), fmt.str, make_wformat_args(args...));
template<class Out, class... Args> Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat_to(std::move(out), loc, fmt.str, make_format_args(args...));
template<class Out, class... Args> Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
Effects: Equivalent to: return vformat_to(std::move(out), loc, fmt.str, make_wformat_args(args...));
template<class Out> Out vformat_to(Out out, string_view fmt, format_args args); template<class Out> Out vformat_to(Out out, wstring_view fmt, wformat_args args); template<class Out> Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args); template<class Out> Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
Let charT be decltype(fmt)​::​value_­type.
Constraints: Out satisfies output_­iterator<const charT&>.
Preconditions: Out models output_­iterator<const charT&>.
Effects: Places the character representation of formatting the arguments provided by args, formatted according to the specifications given in fmt, into the range [out, out + N), where N is the number of characters in that character representation.
If present, loc is used for locale-specific formatting.
Returns: out + N.
Throws: As specified in [format.err.report].
template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, wformat_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, format_string<Args...> fmt, Args&&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
Let
  • charT be decltype(fmt.str)​::​value_­type,
  • N be formatted_­size(fmt, args...) for the functions without a loc parameter and formatted_­size(loc, fmt, args...) for the functions with a loc parameter, and
  • M be clamp(n, 0, N).
Constraints: Out satisfies output_­iterator<const charT&>.
Preconditions: Out models output_­iterator<const charT&>, and formatter<>, charT> meets the BasicFormatter requirements ([formatter.requirements]) for each in Args.
Effects: Places the first M characters of the character representation of formatting the arguments provided by args, formatted according to the specifications given in fmt, into the range [out, out + M).
If present, loc is used for locale-specific formatting.
Returns: {out + M, N}.
Throws: As specified in [format.err.report].
template<class... Args> size_t formatted_size(format_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(wformat_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args); template<class... Args> size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
Let charT be decltype(fmt.str)​::​value_­type.
Preconditions: formatter<>, charT> meets the BasicFormatter requirements ([formatter.requirements]) for each in Args.
Returns: The number of characters in the character representation of formatting arguments args formatted according to specifications given in fmt.
If present, loc is used for locale-specific formatting.
Throws: As specified in [format.err.report].

22.14.6 Formatter [format.formatter]

22.14.6.1 Formatter requirements [formatter.requirements]

A type F meets the BasicFormatter requirements if:
A type F meets the Formatter requirements if it meets the BasicFormatter requirements and the expressions shown in Table 75 are valid and have the indicated semantics.
Given character type charT, output iterator type Out, and formatting argument type T, in Table 74 and Table 75:
  • 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.string]) of the replacement field being formatted in the format string.
If format-spec is empty then either pc.begin() == pc.end() or *pc.begin() == '}'.
Table 74: BasicFormatter requirements [tab:formatter.basic]
Expression
Return type
Requirement
f.parse(pc)
PC​::​iterator
Parses format-spec ([format.string]) for type T in the range [pc.begin(), pc.end()) until the first unmatched character.
Throws format_­error unless the whole range is parsed or the unmatched character is }.
[Note 1:
This allows formatters to emit meaningful error messages.
— end note]
Stores the parsed format specifiers in *this and returns an iterator past the end of the parsed range.
f.format(u, fc)
FC​::​iterator
Formats u according to the specifiers stored in *this, writes the output to fc.out(), and returns an iterator past the end of the output range.
The output shall only depend on u, fc.locale(), fc.arg(n) for any value n of type size_­t, and the range [pc.begin(), pc.end()) from the last call to f.parse(pc).
Table 75: Formatter requirements [tab:formatter]
Expression
Return type
Requirement
f.format(t, fc)
FC​::​iterator
Formats t according to the specifiers stored in *this, writes the output to fc.out(), and returns an iterator past the end of the output range.
The output shall only depend on t, fc.locale(), fc.arg(n) for any value n of type size_­t, and the range [pc.begin(), pc.end()) from the last call to f.parse(pc).
f.format(u, fc)
FC​::​iterator
As above, but does not modify u.

22.14.6.2 Concept formattable [format.formattable]

Let fmt-iter-for<charT> be an unspecified type that models output_­iterator<const charT&> ([iterator.concept.output]).
template<class T, class charT> concept formattable = semiregular<formatter<remove_cvref_t<T>, charT>> && requires(formatter<remove_cvref_t<T>, charT> f, const formatter<remove_cvref_t<T>, charT> cf, T t, basic_format_context<fmt-iter-for<charT>, charT> fc, basic_format_parse_context<charT> pc) { { f.parse(pc) } -> same_­as<basic_format_parse_context<charT>::iterator>; { cf.format(t, fc) } -> same_­as<fmt-iter-for<charT>>; };
A type T and a character type charT model formattable if formatter<remove_­cvref_­t<T>, charT> meets the BasicFormatter requirements ([formatter.requirements]) and, if remove_­reference_­t<T> is const-qualified, the Formatter requirements.

22.14.6.3 Formatter specializations [format.formatter.spec]

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.
A debug-enabled specialization of formatter additionally provides a public, constexpr, non-static member function set_­debug_­format() which modifies the state of the formatter to be as if the type of the std-format-spec parsed by the last call to parse were ?.
Each header that declares the template formatter provides the following enabled specializations:
  • The debug-enabled specializations template<> struct formatter<char, char>; template<> struct formatter<char, wchar_t>; template<> struct formatter<wchar_t, wchar_t>;
  • For each charT, the debug-enabled string type specializations template<> struct formatter<charT*, charT>; template<> struct formatter<const charT*, charT>; template<size_t N> struct formatter<charT[N], 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>;
  • For each charT, for each cv-unqualified arithmetic type ArithmeticT other than char, wchar_­t, char8_­t, char16_­t, or char32_­t, a specialization template<> struct formatter<ArithmeticT, charT>;
  • For each charT, the pointer type specializations template<> struct formatter<nullptr_t, charT>; template<> struct formatter<void*, charT>; template<> struct formatter<const void*, charT>;
The parse member functions of these formatters interpret the format specification as a std-format-spec as described in [format.string.std].
[Note 1:
Specializations such as formatter<wchar_­t, char> and formatter<const char*, wchar_­t> that would require implicit multibyte / wide string or character conversion are disabled.
— end note]
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 and meets the Formatter requirements 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>, and
  • is_­move_­assignable_­v<F>.
An enabled specialization formatter<T, charT> meets the BasicFormatter requirements ([formatter.requirements]).
[Example 1: #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"); // error: disabled formatter std::string s2 = std::format("{}", red); // OK, user-provided formatter std::string s3 = std::format("{}", err{}); // error: disabled formatter — end example]

22.14.6.4 Formatting escaped characters and strings [format.string.escaped]

A character or string can be formatted as escaped to make it more suitable for debugging or for logging.
The escaped string E representation of a string S is constructed by encoding a sequence of characters as follows.
The associated character encoding CE for charT (Table 13) is used to both interpret S and construct E.
  • U+0022 quotation mark (") is appended to E.
  • For each code unit sequence X in S that either encodes a single character, is a shift sequence, or is a sequence of ill-formed code units, processing is in order as follows:
    • If X encodes a single character C, then:
      • If C is one of the characters in Table 76, then the two characters shown as the corresponding escape sequence are appended to E.
      • Otherwise, if C is not U+0020 space and
        • CE is a Unicode encoding and C corresponds to either a UCS scalar value whose Unicode property General_­Category has a value in the groups Separator (Z) or Other (C) or to a UCS scalar value which has the Unicode property Grapheme_­Extend=Yes, as described by table 12 of UAX #44, or
        • CE is not a Unicode encoding and C is one of an implementation-defined set of separator or non-printable characters
        then the sequence \u{hex-digit-sequence} is appended to E, where hex-digit-sequence is the shortest hexadecimal representation of C using lower-case hexadecimal digits.
      • Otherwise, C is appended to E.
    • Otherwise, if X is a shift sequence, the effect on E and further decoding of S is unspecified.
      Recommended practice: A shift sequence should be represented in E such that the original code unit sequence of S can be reconstructed.
    • Otherwise (X is a sequence of ill-formed code units), each code unit U is appended to E in order as the sequence \x{hex-digit-sequence}, where hex-digit-sequence is the shortest hexadecimal representation of U using lower-case hexadecimal digits.
  • Finally, U+0022 quotation mark (") is appended to E.
Table 76: Mapping of characters to escape sequences [tab:format.escape.sequences]
Character
Escape sequence
U+0009 character tabulation
\t
U+000a line feed
\n
U+000d carriage return
\r
U+0022 quotation mark
\"
U+005c reverse solidus
\\
The escaped string representation of a character C is equivalent to the escaped string representation of a string of C, except that:
  • the result starts and ends with U+0027 apostrophe (') instead of U+0022 quotation mark ("), and
  • if C is U+0027 apostrophe, the two characters \' are appended to E, and
  • if C is U+0022 quotation mark, then C is appended unchanged.
[Example 1: string s0 = format("[{}]", "h\tllo"); // s0 has value: [h llo] string s1 = format("[{:?}]", "h\tllo"); // s1 has value: ["h\tllo"] string s3 = format("[{:?}, {:?}]", '\'', '"'); // s3 has value: ['\'', '"'] // The following examples assume use of the UTF-8 encoding string s4 = format("[{:?}]", string("\0 \n \t \x02 \x1b", 9)); // s4 has value: ["\u{0} \n \t \u{2} \u{1b}"] string s5 = format("[{:?}]", "\xc3\x28"); // invalid UTF-8, s5 has value: ["\x{c3}("] — end example]

22.14.6.5 Class template basic_­format_­parse_­context [format.parse.ctx]

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: constexpr explicit 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.
constexpr explicit 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);
Preconditions: 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]).

22.14.6.6 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 noexcept; std::locale locale(); 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 output_­iterator<const charT&>.
format_­context is an alias for a specialization of basic_­format_­context with an output iterator that appends to string, such as back_­insert_­iterator<string>.
Similarly, wformat_­context is an alias for a specialization of basic_­format_­context with an output iterator that appends to wstring.
Recommended practice: For a given type charT, implementations should 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 a uniform interface (such as a span<charT>) and polymorphic reallocation.
basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
Returns: args_­.get(id).
std::locale locale();
Returns: The locale passed to the formatting function if the latter takes one, and std​::​locale() otherwise.
iterator out();
Effects: Equivalent to: return std​::​move(out_­);
void advance_to(iterator it);
Effects: Equivalent to: out_­ = std​::​move(it);
[Example 1: 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 an 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:x<{1}}", s.value, width); } }; std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42" — end example]

22.14.7 Formatting of ranges [format.range]

22.14.7.1 Variable template format_­kind [format.range.fmtkind]

template<ranges::input_­range R> requires same_­as<R, remove_cvref_t<R>> constexpr range_format format_kind<R> = see below;
A program that instantiates the primary template of format_­kind is ill-formed.
For a type R, format_­kind<R> is defined as follows:
  • If same_­as<remove_­cvref_­t<ranges​::​range_­reference_­t<R>>, R> is true, format_­kind<R> is range_­format​::​disabled.
    [Note 1:
    This prevents constraint recursion for ranges whose reference type is the same range type.
    For example, std​::​filesystem​::​path is a range of std​::​filesystem​::​path.
    — end note]
  • Otherwise, if the qualified-id R​::​key_­type is valid and denotes a type:
    • If the qualified-id R​::​mapped_­type is valid and denotes a type, let U be remove_­cvref_­t<ranges​::​range_­reference_­t<R>>.
      If either U is a specialization of pair or U is a specialization of tuple and tuple_­size_­v<U> == 2, format_­kind<R> is range_­format​::​map.
    • Otherwise, format_­kind<R> is range_­format​::​set.
  • Otherwise, format_­kind<R> is range_­format​::​sequence.
Remarks: Pursuant to [namespace.std], users may specialize format_­kind for cv-unqualified program-defined types that model ranges​::​input_­range.
Such specializations shall be usable in constant expressions ([expr.const]) and have type const range_­format.

22.14.7.2 Class template range_­formatter [format.range.formatter]

namespace std { template<class T, class charT = char> requires same_­as<remove_cvref_t<T>, T> && formattable<T, charT> class range_formatter { formatter<T, charT> underlying_; // exposition only basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); // exposition only basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); // exposition only public: constexpr void set_separator(basic_string_view<charT> sep); constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing); constexpr formatter<T, charT>& underlying() { return underlying_; } constexpr const formatter<T, charT>& underlying() const { return underlying_; } template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<ranges::input_­range R, class FormatContext> requires formattable<ranges::range_reference_t<R>, charT> && same_­as<remove_cvref_t<ranges::range_reference_t<R>>, T> typename FormatContext::iterator format(R&& r, FormatContext& ctx) const; }; }
The class template range_­formatter is a utility for implementing formatter specializations for range types.
range_­formatter interprets format-spec as a range-format-spec.
The syntax of format specifications is as follows:
range-format-spec:
range-fill-and-align width n range-type range-underlying-spec
range-fill-and-align:
range-fill align
range-fill:
any character other than { or } or :
range-type:
m
s
?s
range-underlying-spec:
: format-spec
For range_­formatter<T, charT>, the format-spec in a range-underlying-spec, if any, is interpreted by formatter<T, charT>.
The range-fill-and-align is interpreted the same way as a fill-and-align ([format.string.std]).
The productions align and width are described in [format.string].
The n option causes the range to be formatted without the opening and closing brackets.
[Note 1:
This is equivalent to invoking set_­brackets({}, {}).
— end note]
The range-type specifier changes the way a range is formatted, with certain options only valid with certain argument types.
The meaning of the various type options is as specified in Table 77.
Table 77: Meaning of range-type options [tab:formatter.range.type]
Option
Requirements
Meaning
m
T shall be either a specialization of pair or a specialization of tuple such that tuple_­size_­v<T> is 2.
Indicates that the opening bracket should be "{", the closing bracket should be "}", the separator should be ", ", and each range element should be formatted as if m were specified for its tuple-type.
[Note 2:
If the n option is provided in addition to the m option, both the opening and closing brackets are still empty.
— end note]
s
T shall be charT.
Indicates that the range should be formatted as a string.
?s
T shall be charT.
Indicates that the range should be formatted as an escaped string ([format.string.escaped]).
If the range-type is s or ?s, then there shall be no n option and no range-underlying-spec.
constexpr void set_separator(basic_string_view<charT> sep);
Effects: Equivalent to: separator_­ = sep;
constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing);
Effects: Equivalent to: opening-bracket_ = opening; closing-bracket_ = closing;
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Parses the format specifier as a range-format-spec and stores the parsed specifiers in *this.
The values of opening-bracket_­, closing-bracket_­, and separator_­ are modified if and only if required by the range-type or the n option, if present.
If:
  • the range-type is neither s nor ?s,
  • underlying_­.set_­debug_­format() is a valid expression, and
  • there is no range-underlying-spec,
then calls underlying_­.set_­debug_­format().
Returns: An iterator past the end of the range-format-spec.
template<ranges::input_­range R, class FormatContext> requires formattable<ranges::range_reference_t<R>, charT> && same_­as<remove_cvref_t<ranges::range_reference_t<R>>, T> typename FormatContext::iterator format(R&& r, FormatContext& ctx) const;
Effects: Writes the following into ctx.out(), adjusted according to the range-format-spec:
  • If the range-type was s, then as if by formatting basic_­string<charT>(from_­range, r).
  • Otherwise, if the range-type was ?s, then as if by formatting basic_­string<charT>(from_­range, r) as an escaped string ([format.string.escaped]).
  • Otherwise,
Returns: An iterator past the end of the output range.

22.14.7.3 Class template range-default-formatter [format.range.fmtdef]

namespace std { template<ranges::input_­range R, class charT> struct range-default-formatter<range_format::sequence, R, charT> { // exposition only private: using maybe-const-r = fmt-maybe-const<R, charT>; // exposition only range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-r>>, charT> underlying_; // exposition only public: constexpr void set_separator(basic_string_view<charT> sep); constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(maybe-const-r& elems, FormatContext& ctx) const; }; }
constexpr void set_separator(basic_string_view<charT> sep);
Effects: Equivalent to: underlying_­.set_­separator(sep);
constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing);
Effects: Equivalent to: underlying_­.set_­brackets(opening, closing);
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Equivalent to: return underlying_­.parse(ctx);
template<class FormatContext> typename FormatContext::iterator format(maybe-const-r& elems, FormatContext& ctx) const;
Effects: Equivalent to: return underlying_­.format(elems, ctx);

22.14.7.4 Specialization of range-default-formatter for maps [format.range.fmtmap]

namespace std { template<ranges::input_­range R, class charT> struct range-default-formatter<range_format::map, R, charT> { private: using maybe-const-map = fmt-maybe-const<R, charT>; // exposition only using element-type = // exposition only remove_cvref_t<ranges::range_reference_t<maybe-const-map>>; range_formatter<element-type, charT> underlying_; // exposition only public: constexpr range-default-formatter(); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(maybe-const-map& r, FormatContext& ctx) const; }; }
constexpr range-default-formatter();
Mandates: Either:
  • element-type is a specialization of pair, or
  • element-type is a specialization of tuple and tuple_­size_­v<T> == 2.
Effects: Equivalent to: underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}")); underlying_.underlying().set_brackets({}, {}); underlying_.underlying().set_separator(STATICALLY-WIDEN<charT>(": "));
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Equivalent to: return underlying_­.parse(ctx);
template<class FormatContext> typename FormatContext::iterator format(maybe-const-map& r, FormatContext& ctx) const;
Effects: Equivalent to: return underlying_­.format(r, ctx);

22.14.7.5 Specialization of range-default-formatter for sets [format.range.fmtset]

namespace std { template<ranges::input_­range R, class charT> struct range-default-formatter<range_format::set, R, charT> { private: using maybe-const-set = fmt-maybe-const<R, charT>; // exposition only range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-set>>, charT> underlying_; // exposition only public: constexpr range-default-formatter(); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(maybe-const-set& r, FormatContext& ctx) const; }; }
constexpr range-default-formatter();
Effects: Equivalent to: underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Equivalent to: return underlying_­.parse(ctx);
template<class FormatContext> typename FormatContext::iterator format(maybe-const-set& r, FormatContext& ctx) const;
Effects: Equivalent to: return underlying_­.format(r, ctx);

22.14.7.6 Specialization of range-default-formatter for strings [format.range.fmtstr]

namespace std { template<range_format K, ranges::input_­range R, class charT> requires (K == range_format::string || K == range_format::debug_string) struct range-default-formatter<K, R, charT> { private: formatter<basic_string<charT>, charT> underlying_; // exposition only public: template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(see below& str, FormatContext& ctx) const; }; }
Mandates: same_­as<remove_­cvref_­t<range_­reference_­t<R>>, charT> is true.
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Equivalent to: auto i = underlying_.parse(ctx); if constexpr (K == range_format::debug_string) { underlying_.set_debug_format(); } return i;
template<class FormatContext> typename FormatContext::iterator format(see below& r, FormatContext& ctx) const;
The type of r is const R& if ranges​::​input_­range<const R> is true and R& otherwise.
Effects: Let s be a basic_­string<charT> such that ranges​::​equal(s, r) is true.
Equivalent to: return underlying_­.format(s, ctx);

22.14.8 Arguments [format.arguments]

22.14.8.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, float, double, long double, const char_type*, basic_string_view<char_type>, const void*, handle> value; // exposition only template<class T> explicit basic_format_arg(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(T* p) noexcept; // 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;
Postconditions: !(*this).
template<class T> explicit basic_format_arg(T&& v) noexcept;
Constraints: The template specialization typename Context::template formatter_type<remove_cvref_t<T>> meets the BasicFormatter requirements ([formatter.requirements]).
The extent to which an implementation determines that the specialization meets the BasicFormatter requirements is unspecified, except that as a minimum the expression typename Context::template formatter_type<remove_cvref_t<T>>() .format(declval<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; 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);
Preconditions: 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 basic_­string_­view<char_­type>(s.data(), s.size()).
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 1:
Constructing basic_­format_­arg from a pointer to a member is ill-formed unless the user provides an enabled specialization of formatter for that 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(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(T&& val) noexcept;
Let
  • TD be remove_­cvref_­t<T>,
  • const-formattable be true if typename Context​::​template formatter_­type<TD>()
    .format(declval<const TD&>(), declval<Context&>())
    is well-formed, otherwise false,
  • TQ be const TD if const-formattable is true and TD otherwise.
Mandates: const-formattable || !is_­const_­v<remove_­reference_­t<T>> is true.
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<TD> f; parse_ctx.advance_to(f.parse(parse_ctx)); format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(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_­);
template<class Visitor, class Context> decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
Effects: Equivalent to: return visit(forward<Visitor>(vis), arg.value);

22.14.8.2 Class template format-arg-store [format.arg.store]

namespace std { template<class Context, class... Args> class format-arg-store { // exposition only array<basic_format_arg<Context>, sizeof...(Args)> args; // exposition only }; }
An instance of format-arg-store stores formatting arguments.
template<class Context = format_context, class... Args> format-arg-store<Context, Args...> make_format_args(Args&&... fmt_args);
Preconditions: The type typename Context​::​template formatter_­type<> meets the BasicFormatter requirements ([formatter.requirements]) for each in Args.
Returns: An object of type format-arg-store<Context, Args...> whose args data member is initialized with {basic_­format_­arg<Context>(fmt_­args)...}.
template<class... Args> format-arg-store<wformat_context, Args...> make_wformat_args(Args&&... args);
Effects: Equivalent to: return make_­format_­args<wformat_­context>(args...);

22.14.8.3 Class template basic_­format_­args [format.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.
Implementations should optimize the representation of basic_­format_­args for a small number of formatting arguments.
[Note 1:
For example, by storing indices of type alternatives separately from values and packing the former.
— end note]
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>().

22.14.9 Tuple formatter [format.tuple]

For each of pair and tuple, the library provides the following formatter specialization where pair-or-tuple is the name of the template:
namespace std { template<class charT, formattable<charT>... Ts> struct formatter<pair-or-tuple<Ts...>, charT> { private: tuple<formatter<remove_cvref_t<Ts>, charT>...> underlying_; // exposition only basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("("); // exposition only basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>(")"); // exposition only public: constexpr void set_separator(basic_string_view<charT> sep); constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(see below& elems, FormatContext& ctx) const; }; }
The parse member functions of these formatters interpret the format specification as a tuple-format-spec according to the following syntax:
tuple-format-spec:
tuple-fill-and-align width tuple-type
tuple-fill-and-align:
tuple-fill align
tuple-fill:
any character other than { or } or :
tuple-type:
m
n
The tuple-fill-and-align is interpreted the same way as a fill-and-align ([format.string.std]).
The productions align and width are described in [format.string].
The tuple-type specifier changes the way a pair or tuple is formatted, with certain options only valid with certain argument types.
The meaning of the various type options is as specified in Table 78.
Table 78: Meaning of tuple-type options [tab:formatter.tuple.type]
Option
Requirements
Meaning
m
sizeof...(Ts) == 2
Equivalent to: set_separator(STATICALLY-WIDEN<charT>(": ")); set_brackets({}, {});
n
none
Equivalent to: set_­brackets({}, {});
none
none
No effects
constexpr void set_separator(basic_string_view<charT> sep);
Effects: Equivalent to: separator_­ = sep;
constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing);
Effects: Equivalent to: opening-bracket_ = opening; closing-bracket_ = closing;
template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);
Effects: Parses the format specifier as a tuple-format-spec and stores the parsed specifiers in *this.
The values of opening-bracket_­, closing-bracket_­, and separator_­ are modified if and only if required by the tuple-type, if present.
For each element e in underlying_­, if e.set_­debug_­format() is a valid expression, calls e.set_­debug_­format().
Returns: An iterator past the end of the tuple-format-spec.
template<class FormatContext> typename FormatContext::iterator format(see below& elems, FormatContext& ctx) const;
The type of elems is:
  • If (formattable<const Ts, charT> && ...) is true, const pair-or-tuple<Ts...>&.
  • Otherwise pair-or-tuple<Ts...>&.
Effects: Writes the following into ctx.out(), adjusted according to the tuple-format-spec:
  • opening-bracket_­,
  • for each index I in the [0, sizeof...(Ts)):
    • if I != 0, separator_­,
    • the result of writing get<I>(elems) via get<I>(underlying_­), and
  • closing-bracket_­.
Returns: An iterator past the end of the output range.

22.14.10 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);
Postconditions: strcmp(what(), what_­arg.c_­str()) == 0.
format_error(const char* what_arg);
Postconditions: strcmp(what(), what_­arg) == 0.