[format.string.std] (original) (raw)
28 Text processing library [text]
28.5 Formatting [format]
28.5.2 Format string [format.string]
28.5.2.2 Standard format specifiers [format.string.std]
Each formatter specialization described in [format.formatter.spec]for fundamental and string types interprets format-spec as a_std-format-spec_.
[Note 1:
The format specification can be used to specify such details as minimum 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 }
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 P s x X ?
Field widths are specified in field width units; the number of column positions required to display a sequence of characters in a terminal.
The minimum field widthis the number of field width units a replacement field minimally requires of the formatted sequence of characters produced for a format argument.
The estimated field width is the number of field width units that are required for the formatted sequence of characters produced for a format argument independent of the effects of the width option.
The padding width is the greater of 0 and the difference of the minimum field width and the estimated field width.
[Note 2:
The POSIX wcswidth function is an example of a function that, given a string, returns the number of column positions required by a terminal to display the string.
— _end note_]
The fill character is the character denoted by the fill option or, if the fill option is absent, the space character.
For a format specification in UTF-8, UTF-16, or UTF-32, the fill character corresponds to a single Unicode scalar value.
[Note 3:
The presence of a fill option 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 the fill and align options are both absent.
— _end note_]
The align option applies to all argument types.
The meaning of the various alignment options is as specified in Table 104.
[Example 1: char c = 120; string s0 = format("{:6}", 42); string s1 = format("{:6}", 'x'); string s2 = format("{:*<6}", 'x'); string s3 = format("{:*>6}", 'x'); string s4 = format("{:*^6}", 'x'); string s5 = format("{:6d}", c); string s6 = format("{:6}", true); string s7 = format("{:*<6.3}", "123456"); string s8 = format("{:02}", 1234); string s9 = format("{:*<}", "12"); string sA = format("{:*<6}", "12345678"); string sB = format("{:🤡^6}", "x"); string sC = format("{:*^6}", "🤡🤡🤡"); — _end example_]
[Note 4:
The fill, align, and 0 options have no effect when the minimum field width is not greater than the estimated field width because padding width is 0 in that case.
Since fill characters are assumed to have a field width of 1, use of a character with a different field width can produce misaligned output.
The 🤡 (U+1f921 clown face) character has a field width of 2.
The examples above that include that character illustrate the effect of the field width when that character is used as a fill character as opposed to when it is used as a formatting argument.
— _end note_]
Table 104 — Meaning of align options [tab:format.align]
| Forces the formatted argument to be aligned to the start of the field by inserting n fill characters after the formatted argument where n is the padding width. This is the default for non-arithmetic non-pointer types, charT, and bool, unless an integer presentation type is specified. |
|---|
| Forces the formatted argument to be aligned to the end of the field by inserting n fill characters before the formatted argument where n is the padding width. This is the default for arithmetic types other than charT and bool, pointer types, or when an integer presentation type is specified. |
| Forces the formatted argument to be centered within the field by insertingfill characters before andfill characters after the formatted argument, wheren is the padding width. |
The sign option is only valid for arithmetic types other than charT and boolor when an integer presentation type is specified.
The meaning of the various options is as specified in Table 105.
Table 105 — Meaning of sign options [tab:format.sign]
| 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 5: 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). |
| 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. |
The sign option applies to floating-point infinity and NaN.
[Example 2: double inf = numeric_limits<double>::infinity();double nan = numeric_limits<double>::quiet_NaN(); string s0 = format("{0:},{0:+},{0:-},{0: }", 1); string s1 = format("{0:},{0:+},{0:-},{0: }", -1); string s2 = format("{0:},{0:+},{0:-},{0: }", inf); string s3 = format("{0:},{0:+},{0:-},{0: }", nan); — _end example_]
The # option causes thealternate formto be used for the conversion.
This option is valid for arithmetic types other thancharT and boolor 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 107into 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.
The 0 option is valid for arithmetic types other than charT and bool, pointer types, or when an integer presentation type is specified.
For formatting arguments that have a value other than an infinity or a NaN, this option pads the formatted argument by inserting the 0 character n times following the sign or base prefix indicators (if any) where n is 0 if the align option is present and is the padding width otherwise.
[Example 3: char c = 120; string s1 = format("{:+06d}", c); string s2 = format("{:#06x}", 0xa); string s3 = format("{:<06}", -42); string s4 = format("{:06}", inf); — _end example_]
The width option specifies the minimum field width.
If the width option is absent, the minimum field width is 0.
If { arg-id } is used in a width or precision option, the value of the corresponding formatting argument is used as the value of the option.
The option is valid only if the corresponding formatting argument is of standard signed or unsigned integer type.
If its value is negative, an exception of type format_error is thrown.
If positive-integer is used in a_width_ option, the value of the _positive-integer_is interpreted as a decimal integer and used as the value of the option.
For the purposes of width computation, a string is assumed to be in a locale-independent,implementation-defined encoding.
Implementations should use either UTF-8, UTF-16, or UTF-32, on platforms capable of displaying Unicode text in a terminal.
[Note 6:
This is the case for Windows®-based237and many POSIX-based operating systems.
— _end note_]
For a sequence of characters in UTF-8, UTF-16, or UTF-32, an implementation should use as its field width the sum of the field widths of the first code point of each extended grapheme cluster.
Extended grapheme clusters are defined by UAX #29 of the Unicode Standard.
The following code points have a field width of 2:
- any code point with the East_Asian_Width="W" orEast_Asian_Width="F" property as described by UAX #44 of the Unicode Standard
- U+4dc0 – U+4dff (Yijing Hexagram Symbols)
- U+1f300 – U+1f5ff (Miscellaneous Symbols and Pictographs)
- U+1f900 – U+1f9ff (Supplemental Symbols and Pictographs)
The field width of all other code points is 1.
For a sequence of characters in neither UTF-8, UTF-16, nor UTF-32, the field width is unspecified.
The precision option is valid for floating-point and string types.
For floating-point types, the value of this option specifies the precision to be used for the floating-point presentation type.
For string types, this option specifies the longest prefix of the formatted argument to be included in the replacement field such that the field width of the prefix is no greater than the value of this option.
If nonnegative-integer is used in a precision option, the value of the decimal integer is used as the value of the option.
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.
- For integral types, the locale-specific form causes the context's locale to be used to insert the appropriate digit group separator characters.
- For floating-point types, the locale-specific form causes the context's locale to be used to insert the appropriate digit group and radix separator characters.
- For the textual representation of bool, the locale-specific form causes the context's locale to be used to insert the appropriate string as if obtained with numpunct::truename or numpunct::falsename.
The type determines how the data should be presented.
The available string presentation types are specified in Table 106.
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 7:
Additional padding and adjustments are performed prior to copying the output through the output iterator as specified by the format specifiers.
— _end note_]
The available integer presentation types for integral types other than bool and charTare specified in Table 107.
[Example 4: string s0 = format("{}", 42); string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); string s2 = format("{0:#x} {0:#X}", 42); string s3 = format("{:L}", 1234); — _end example_]
Table 107 — 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 thatthe 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 andthe base prefix is 0X. |
| 🔗none | The same as d. [Note 8: If the formatting argument type is charT or bool, the default is instead c or s, respectively. — _end note_] |
The available charT presentation types are specified in Table 108.
Table 108 — Meaning of type options for charT [tab:format.type.char]
| Copies the character to the output. |
|---|
| As specified in Table 107with value converted to the unsigned version of the underlying type. |
The available bool presentation types are specified in Table 109.
Table 109 — Meaning of type options for bool [tab:format.type.bool]
| Copies textual representation, either true or false, to the output. |
|---|
| As specified in Table 107for the valuestatic_cast<unsigned char>(value). |
The available floating-point presentation types and their meanings for values other than infinity and NaN are specified in Table 110.
For lower-case presentation types, infinity and NaN are formatted asinf and nan, respectively.
For upper-case presentation types, infinity and NaN are formatted asINF and NAN, respectively.
[Note 9:
In either case, a sign is included if indicated by the sign option.
— _end note_]
Table 110 — Meaning of type options for floating-point types [tab:format.type.float]
| 🔗Type | Meaning |
|---|---|
| 🔗a | If precision is specified, equivalent toto_chars(first, last, value, chars_format::hex, precision) where precision is the specified formatting precision; equivalent toto_chars(first, last, value, chars_format::hex) otherwise. |
| 🔗A | The same as a, except that it uses uppercase letters for digits above 9 andP to indicate the exponent. |
| 🔗e | Equivalent toto_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 toto_chars(first, last, value, chars_format::fixed, precision) where precision is the specified formatting precision, or 6 if precision is not specified. |
| 🔗g | Equivalent toto_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 toto_chars(first, last, value, chars_format::general, precision) where precision is the specified formatting precision; equivalent toto_chars(first, last, value) otherwise. |
The available pointer presentation types and their mapping toto_chars are specified in Table 111.
[Note 10:
Pointer presentation types also apply to nullptr_t.
— _end note_]
Table 111 — Meaning of type options for pointer types [tab:format.type.ptr]
| If uintptr_t is defined,to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) with the prefix 0x inserted immediately before the output of to_chars; otherwise, implementation-defined. |
|---|
| The same as p, except that it uses uppercase letters for digits above 9 and the base prefix is 0X. |