[format.string.general]

# 28 Text processing library [[text]](./#text)

## 28.5 Formatting [[format]](format#string.general)

### 28.5.2 Format string [[format.string]](format.string#general)

#### 28.5.2.1 General [format.string.general]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L5914)

A [*format string*](#def:format_string "28.5.2.1 General [format.string.general]") for arguments args is
a (possibly empty) sequence of[*replacement fields*](#def:replacement_field,format_string "28.5.2.1 General [format.string.general]"),[*escape sequences*](#def:escape_sequence,format_string "28.5.2.1 General [format.string.general]"),
and characters other than { and }[.](#1.sentence-1)

Let charT be the character type of the format string[.](#1.sentence-2)

Each character that is not part of
a replacement field or an escape sequence
is copied unchanged to the output[.](#1.sentence-3)

An escape sequence is one of {{ or }}[.](#1.sentence-4)

It is replaced with { or }, respectively, in the output[.](#1.sentence-5)

The syntax of replacement fields is as follows:

replacement-field :  
{ arg-idopt format-specifieropt }

arg-id :  
0  
positive-integer

positive-integer :  
[*nonzero-digit*](lex.icon#nt:nonzero-digit "5.13.2 Integer literals [lex.icon]")  
positive-integer [*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]")

nonnegative-integer :  
[*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]")  
nonnegative-integer [*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]")

[*nonzero-digit*](lex.icon#nt:nonzero-digit "5.13.2 Integer literals [lex.icon]") : one of  
1 2 3 4 5 6 7 8 9

[*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]") : 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; cannot start with }

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L5972)

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[.](#2.sentence-1)

If there is no argument with
the index *arg-id* in args,
the string is not a format string for args[.](#2.sentence-2)

The optional *format-specifier* field
explicitly specifies a format for the replacement value[.](#2.sentence-3)

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L5983)

[*Example [1](#example-1)*: string s = format("{0}-{{", 8); // value of s is "8-{" — *end example*]

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L5990)

If all *arg-id**s* 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[.](#4.sentence-1)

If some *arg-id**s* are omitted and some are present,
the string is not a format string[.](#4.sentence-2)

[*Note [1](#note-1)*:

A format string cannot contain a
mixture of automatic and manual indexing[.](#4.sentence-3)

— *end note*]

[*Example [2](#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*]

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6012)

The *format-spec* field contains[*format specifications*](#def:format_specification,format_string "28.5.2.1 General [format.string.general]") that define how the value should be presented[.](#5.sentence-1)

Each type can define its own
interpretation of the *format-spec* field[.](#5.sentence-2)

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[.](#5.sentence-3)

[*Example [3](#example-3)*: 

- [(5.1)](#5.1)

  For arithmetic, pointer, and string types
the *format-spec* is interpreted as a *std-format-spec* as described in [[format.string.std]](format.string.std "28.5.2.2 Standard format specifiers")[.](#5.1.sentence-1)

- [(5.2)](#5.2)

  For chrono types
the *format-spec* is interpreted as a *chrono-format-spec* as described in [[time.format]](time.format "30.12 Formatting")[.](#5.2.sentence-1)

- [(5.3)](#5.3)

  For user-defined formatter specializations,
the behavior of the parse member function
determines how the *format-spec* is interpreted[.](#5.3.sentence-1)

— *end example*]