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