[format.string] - C++17 → C++20

Files changed (1) hide show

tmp/tmp4djppoav/{from.md → to.md} +434 -0

tmp/tmp4djppoav/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,434 @@

+### Format string <a id="format.string">[[format.string]]</a>
+#### In general <a id="format.string.general">[[format.string.general]]</a>
+A *format string* for arguments `args` 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:
+``` bnf
+replacement-field
+    '{' arg-idₒₚₜ format-specifierₒₚₜ '}'
+```
+``` bnf
+arg-id
+    '0'
+    positive-integer
+```
+``` bnf
+positive-integer
+    nonzero-digit
+    positive-integer digit
+```
+``` bnf
+nonnegative-integer
+    digit
+    nonnegative-integer digit
+```
+``` bnf
+nonzero-digit one of
+    '1 2 3 4 5 6 7 8 9'
+```
+``` bnf
+digit one of
+    '0 1 2 3 4 5 6 7 8 9'
+```
+``` bnf
+format-specifier
+    ':' format-spec
+```
+``` bnf
+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. If there is no argument with the index *arg-id* in
+`args`, the string is not a format string for `args`. The optional
+*format-specifier* field explicitly specifies a format for the
+replacement value.
+[*Example 1*:
+``` cpp
+string s = format("{0}-{{", 8);         // value of s is "8-{"
+```
+— *end example*]
+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. If some *arg-id*s are omitted and some are present, the
+string is not a format string.
+[*Note 1*: A format string cannot contain a mixture of automatic and
+manual indexing. — *end note*]
+[*Example 2*:
+``` cpp
+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. 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`.
+[*Example 3*:
+- 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*]
+#### Standard format specifiers <a id="format.string.std">[[format.string.std]]</a>
+Each `formatter` specializations 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 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:
+``` bnf
+std-format-spec
+    fill-and-alignₒₚₜ signₒₚₜ '#'ₒₚₜ '0'ₒₚₜ widthₒₚₜ precisionₒₚₜ 'L'ₒₚₜ typeₒₚₜ
+```
+``` bnf
+fill-and-align
+    fillₒₚₜ align
+```
+``` bnf
+fill
+    any character other than \{ or \}
+```
+``` bnf
+align one of
+    '< > ^'
+```
+``` bnf
+sign one of
+    '+ -' space
+```
+``` bnf
+width
+    positive-integer
+    '{' arg-idₒₚₜ '}'
+```
+``` bnf
+precision
+    '.' nonnegative-integer
+    '.' '{' arg-idₒₚₜ '}'
+```
+``` bnf
+type one of
+    'a A b B c d e E f F g G o p s x X'
+```
+[*Note 2*: 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*]
+The *align* specifier applies to all argument types. The meaning of the
+various alignment options is as specified in [[format.align]].
+[*Example 1*:
+``` cpp
+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 3*: 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: Meaning of align options** <a id="format.align">[format.align]</a>
+| 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 $\bigl\lfloor \frac{n}{2} \bigr\rfloor$ characters before and $\bigl\lceil \frac{n}{2} \bigr\rceil$ characters after the value, where $n$ is the total number of fill characters to insert. |
+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 [[format.sign]].
+[*Note 4*: For negative numbers and negative zero the output of
+`to_chars` will already contain the sign so no additional transformation
+is performed. — *end note*]
+The *sign* option applies to floating-point infinity and NaN.
+[*Example 2*:
+``` cpp
+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*]
+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 [[format.type.int]] 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.
+If `{ \opt{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.
+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.
+The *width* of a string is defined as the estimated number of column
+positions appropriate for displaying it in a terminal.
+[*Note 5*: This is similar to the semantics of the POSIX `wcswidth`
+function. — *end note*]
+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 6*: This is the case for Windows-based and many POSIX-based
+operating systems. — *end note*]
+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:
+- `U+1100-U+115F`
+- `U+2329-U+232A`
+- `U+2E80-U+303E`
+- `U+3040-U+A4CF`
+- `U+AC00-U+D7A3`
+- `U+F900-U+FAFF`
+- `U+FE10-U+FE19`
+- `U+FE30-U+FE6F`
+- `U+FF00-U+FF60`
+- `U+FFE0-U+FFE6`
+- `U+1F300-U+1F64F`
+- `U+1F900-U+1F9FF`
+- `U+20000-U+2FFFD`
+- `U+30000-U+3FFFD`
+The estimated width of other code points is 1.
+For a string in a non-Unicode encoding, the width of a string is
+unspecified.
+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 3*:
+``` cpp
+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*]
+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.
+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
+[[format.type.string]].
+**Table: Meaning of type options for strings** <a id="format.type.string">[format.type.string]</a>
+| Type      | Meaning                          |
+| --------- | -------------------------------- |
+| none, `s` | Copies the string to the output. |
+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 `charT` are specified in [[format.type.int]].
+[*Example 4*:
+``` cpp
+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*]
+[*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
+[[format.type.char]].
+**Table: Meaning of type options for `charT`** <a id="format.type.char">[format.type.char]</a>
+| Type                           | Meaning                              |
+| ------------------------------ | ------------------------------------ |
+| none, `c`                      | Copies the character to the output.  |
+| % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]]. |
+The available `bool` presentation types are specified in
+[[format.type.bool]].
+**Table: Meaning of type options for `bool`** <a id="format.type.bool">[format.type.bool]</a>
+| Type                                | Meaning                                                                                |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| none, `s`                           | Copies textual representation, either `true` or `false`, to the output.                |
+| % `b`, `B`, `c`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]] for the value `static_cast<unsigned char>(value)`. |
+The available floating-point presentation types and their meanings for
+values other than infinity and NaN are specified in
+[[format.type.float]]. 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 9*: In either case, a sign is included if indicated by the
+*sign* option. — *end note*]
+**Table: Meaning of type options for floating-point types** <a id="format.type.float">[format.type.float]</a>
+| Type       | Meaning                                                                                                                                                                                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `a`        | If precision is specified, equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::hex, precision) \end{codeblock} where `precision` is the specified formatting precision; equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::hex) \end{codeblock} 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 \begin{codeblock} to_chars(first, last, value, chars_format::scientific, precision) \end{codeblock} 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 \begin{codeblock} to_chars(first, last, value, chars_format::fixed, precision) \end{codeblock} where `precision` is the specified formatting precision, or `6` if precision is not specified.                                                                                               |
+| % `g`      | Equivalent to \begin{codeblock} to_chars(first, last, value, chars_format::general, precision) \end{codeblock} 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 \begin{codeblock} to_chars(first, last, value, chars_format::general, precision) \end{codeblock} where `precision` is the specified formatting precision; equivalent to \begin{codeblock} to_chars(first, last, value) \end{codeblock} otherwise.                |
+The available pointer presentation types and their mapping to `to_chars`
+are specified in [[format.type.ptr]].
+[*Note 10*: Pointer presentation types also apply to
+`nullptr_t`. — *end note*]
+**Table: Meaning of type options for pointer types** <a id="format.type.ptr">[format.type.ptr]</a>
+| Type      | Meaning                                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| none, `p` | If `uintptr_t` is defined, \begin{codeblock} to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) \end{codeblock} with the prefix `0x` added to the output; otherwise, implementation-defined. |

Diff to HTML by rtfpessoa