20 General utilities library [utilities]

20.20 Formatting [format]

20.20.2 Format string [format.string]

20.20.2.2 Standard format specifiers [format.string.std]

1
#
Each formatter specializations described in [format.formatter.spec] for fundamental and string types interprets format-spec as a std-format-spec.
[Note
:
The format specification can be used to specify such details as field width, alignment, padding, and decimal precision.
Some of the formatting options are only supported for arithmetic types.
— end note
]
The syntax of format specifications is as follows:
std-format-spec:
fill-and-align sign # 0 width precision L type
fill-and-align:
fill align
fill:
any character other than { or }
align: one of
< > ^
sign: one of
+ - space
width:
positive-integer
{ arg-id }
precision:
. nonnegative-integer
. { arg-id }
type: one of
a A b B c d e E f F g G o p s x X
2
#
[Note
:
The fill character can be any character other than { or }.
The presence of a fill character is signaled by the character following it, which must be one of the alignment options.
If the second character of std-format-spec is not a valid alignment option, then it is assumed that both the fill character and the alignment option are absent.
— end note
]
3
#
The align specifier applies to all argument types.
The meaning of the various alignment options is as specified in Table 59.
[Example
: 
char c = 120;
string s0 = format("{:6}", 42);         // value of s0 is "    42"
string s1 = format("{:6}", 'x');        // value of s1 is "x     "
string s2 = format("{:*<6}", 'x');      // value of s2 is "x*****"
string s3 = format("{:*>6}", 'x');      // value of s3 is "*****x"
string s4 = format("{:*^6}", 'x');      // value of s4 is "**x***"
string s5 = format("{:6d}", c);         // value of s5 is "   120"
string s6 = format("{:6}", true);       // value of s6 is "true  "
— end example
]
[Note
:
Unless a minimum field width is defined, the field width is determined by the size of the content and the alignment option has no effect.
— end note
]
Table 59: Meaning of align options   [tab:format.align]
Option
Meaning
<
Forces the field to be aligned to the start of the available space.
This is the default for non-arithmetic types, charT, and bool, unless an integer presentation type is specified.
>
Forces the field to be aligned to the end of the available space.
This is the default for arithmetic types other than charT and bool or when an integer presentation type is specified.
^
Forces the field to be centered within the available space by inserting characters before and characters after the value, where n is the total number of fill characters to insert.
4
#
The sign option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified.
The meaning of the various options is as specified in Table 60.
Table 60: Meaning of sign options   [tab:format.sign]
Option
Meaning
+
Indicates that a sign should be used for both non-negative and negative numbers.
The + sign is inserted before the output of to_­chars for non-negative numbers other than negative zero.
[Note
:
For negative numbers and negative zero the output of to_­chars will already contain the sign so no additional transformation is performed.
— end note
]
-
Indicates that a sign should be used for negative numbers and negative zero only (this is the default behavior).
space
Indicates that a leading space should be used for non-negative numbers other than negative zero, and a minus sign for negative numbers and negative zero.
5
#
The sign option applies to floating-point infinity and NaN.
[Example
: 
double inf = numeric_limits<double>::infinity();
double nan = numeric_limits<double>::quiet_NaN();
string s0 = format("{0:},{0:+},{0:-},{0: }", 1);        // value of s0 is "1,+1,1, 1"
string s1 = format("{0:},{0:+},{0:-},{0: }", -1);       // value of s1 is "-1,-1,-1,-1"
string s2 = format("{0:},{0:+},{0:-},{0: }", inf);      // value of s2 is "inf,+inf,inf, inf"
string s3 = format("{0:},{0:+},{0:-},{0: }", nan);      // value of s3 is "nan,+nan,nan, nan"
— end example
]
6
#
The # option causes the alternate form to be used for the conversion.
This option is valid for arithmetic types other than charT and bool or when an integer presentation type is specified, and not otherwise.
For integral types, the alternate form inserts the base prefix (if any) specified in Table 62 into the output after the sign character (possibly space) if there is one, or before the output of to_­chars otherwise.
For floating-point types, the alternate form causes the result of the conversion of finite values to always contain a decimal-point character, even if no digits follow it.
Normally, a decimal-point character appears in the result of these conversions only if a digit follows it.
In addition, for g and G conversions, trailing zeros are not removed from the result.
7
#
If { arg-id } is used in a width or precision, the value of the corresponding formatting argument is used in its place.
If the corresponding formatting argument is not of integral type, or its value is negative for precision or non-positive for width, an exception of type format_­error is thrown.
8
#
The positive-integer in width is a decimal integer defining the minimum field width.
If width is not specified, there is no minimum field width, and the field width is determined based on the content of the field.
9
#
The width of a string is defined as the estimated number of column positions appropriate for displaying it in a terminal.
[Note
:
This is similar to the semantics of the POSIX wcswidth function.
— end note
]
10
#
For the purposes of width computation, a string is assumed to be in a locale-independent, implementation-defined encoding.
Implementations should use a Unicode encoding on platforms capable of displaying Unicode text in a terminal.
[Note
:
This is the case for Windows-based and many POSIX-based operating systems.
— end note
]
11
#
For a string in a Unicode encoding, implementations should estimate the width of a string as the sum of estimated widths of the first code points in its extended grapheme clusters.
The extended grapheme clusters of a string are defined by UAX #29.
The estimated width of the following code points is 2: The estimated width of other code points is 1.
12
#
For a string in a non-Unicode encoding, the width of a string is unspecified.
13
#
A zero (0) character preceding the width field pads the field with leading zeros (following any indication of sign or base) to the field width, except when applied to an infinity or NaN. This option is only valid for arithmetic types other than charT and bool or when an integer presentation type is specified.
If the 0 character and an align option both appear, the 0 character is ignored.
[Example
: 
char c = 120;
string s1 = format("{:+06d}", c);       // value of s1 is "+00120"
string s2 = format("{:#06x}", 0xa);     // value of s2 is "0x000a"
string s3 = format("{:<06}", -42);      // value of s3 is "-42   " (0 is ignored because of < alignment)
— end example
]
14
#
The nonnegative-integer in precision is a decimal integer defining the precision or maximum field size.
It can only be used with floating-point and string types.
For floating-point types this field specifies the formatting precision.
For string types, this field provides an upper bound for the estimated width of the prefix of the input string that is copied into the output.
For a string in a Unicode encoding, the formatter copies to the output the longest prefix of whole extended grapheme clusters whose estimated width is no greater than the precision.
15
#
When the L option is used, the form used for the conversion is called the locale-specific form.
The L option is only valid for arithmetic types, and its effect depends upon the type.
16
#
The type determines how the data should be presented.
17
#
The available string presentation types are specified in Table 61.
Table 61: Meaning of type options for strings   [tab:format.type.string]
Type
Meaning
none, s
Copies the string to the output.
18
#
The meaning of some non-string presentation types is defined in terms of a call to to_­chars.
In such cases, let [first, last) be a range large enough to hold the to_­chars output and value be the formatting argument value.
Formatting is done as if by calling to_­chars as specified and copying the output through the output iterator of the format context.
[Note
:
Additional padding and adjustments are performed prior to copying the output through the output iterator as specified by the format specifiers.
— end note
]
19
#
The available integer presentation types for integral types other than bool and charT are specified in Table 62.
[Example
: 
string s0 = format("{}", 42);                           // value of s0 is "42"
string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42);      // value of s1 is "101010 42 52 2a"
string s2 = format("{0:#x} {0:#X}", 42);                // value of s2 is "0x2a 0X2A"
string s3 = format("{:L}", 1234);                       // value of s3 might be "1,234"
                                                        // (depending on the locale)
— end example
]
Table 62: Meaning of type options for integer types   [tab:format.type.int]
Type
Meaning
b
to_­chars(first, last, value, 2); the base prefix is 0b.
B
The same as b, except that the base prefix is 0B.
c
Copies the character static_­cast<charT>(value) to the output.
Throws format_­error if value is not in the range of representable values for charT.
d
to_­chars(first, last, value).
o
to_­chars(first, last, value, 8); the base prefix is 0 if value is nonzero and is empty otherwise.
x
to_­chars(first, last, value, 16); the base prefix is 0x.
X
The same as x, except that it uses uppercase letters for digits above 9 and the base prefix is 0X.
none
The same as d.
[Note
:
If the formatting argument type is charT or bool, the default is instead c or s, respectively.
— end note
]
20
#
The available charT presentation types are specified in Table 63.
Table 63: Meaning of type options for charT   [tab:format.type.char]
Type
Meaning
none, c
Copies the character to the output.
b, B, d, o, x, X
As specified in Table 62.
21
#
The available bool presentation types are specified in Table 64.
Table 64: Meaning of type options for bool   [tab:format.type.bool]
Type
Meaning
none, s
Copies textual representation, either true or false, to the output.
b, B, c, d, o, x, X
As specified in Table 62 for the value static_­cast<unsigned char>(value).
22
#
The available floating-point presentation types and their meanings for values other than infinity and NaN are specified in Table 65.
For lower-case presentation types, infinity and NaN are formatted as inf and nan, respectively.
For upper-case presentation types, infinity and NaN are formatted as INF and NAN, respectively.
[Note
:
In either case, a sign is included if indicated by the sign option.
— end note
]
Table 65: Meaning of type options for floating-point types   [tab:format.type.float]
Type
Meaning
a
If precision is specified, equivalent to 
to_chars(first, last, value, chars_format::hex, precision)
where precision is the specified formatting precision; equivalent to 
to_chars(first, last, value, chars_format::hex)
otherwise.
A
The same as a, except that it uses uppercase letters for digits above 9 and P to indicate the exponent.
e
Equivalent to 
to_chars(first, last, value, chars_format::scientific, precision)
where precision is the specified formatting precision, or 6 if precision is not specified.
E
The same as e, except that it uses E to indicate exponent.
f, F
Equivalent to 
to_chars(first, last, value, chars_format::fixed, precision)
where precision is the specified formatting precision, or 6 if precision is not specified.
g
Equivalent to 
to_chars(first, last, value, chars_format::general, precision)
where precision is the specified formatting precision, or 6 if precision is not specified.
G
The same as g, except that it uses E to indicate exponent.
none
If precision is specified, equivalent to 
to_chars(first, last, value, chars_format::general, precision)
where precision is the specified formatting precision; equivalent to 
to_chars(first, last, value)
otherwise.
23
#
The available pointer presentation types and their mapping to to_­chars are specified in Table 66.
[Note
:
Pointer presentation types also apply to nullptr_­t.
— end note
]
Table 66: Meaning of type options for pointer types   [tab:format.type.ptr]
Type
Meaning
none, p
If uintptr_­t is defined, 
to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16)
with the prefix 0x added to the output; otherwise, implementation-defined.