20 General utilities library [utilities]

20.20 Formatting [format]

20.20.2 Format string [format.string] In general [format.string.general]

A format string 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:
	{ arg-id format-specifier }
	positive-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-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.
The optional format-specifier field explicitly specifies a format for the replacement value.
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.
A format string cannot contain a mixture of automatic and manual indexing.
— end note
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.
  • 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