133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
[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*]
|