20 General utilities library [utilities]

20.20 Formatting [format]

20.20.2 Format string [format.string]

20.20.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

_{o p t}

format-specifier

_{o p t}

}

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), // throws format_error string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing), // throws format_error — 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:

(5.1)
For arithmetic, pointer, and string types the format-spec is interpreted as a std-format-spec as described in ([format.string.std]).
(5.2)
For chrono types the format-spec is interpreted as a chrono-format-spec as described in ([time.format]).
(5.3)
For user-defined formatter specializations, the behavior of the parse member function determines how the format-spec is interpreted.

— end example]