[format.string] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpo1tofvmw/{from.md → to.md} +24 -20

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

@@ -1,8 +1,8 @@
 ### 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
@@ -48,11 +48,11 @@ 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
@@ -97,14 +97,14 @@ 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*]
@@ -159,11 +159,11 @@ precision
     '.' '{' arg-idₒₚₜ '}'
 ```
 ``` bnf
 type one of
-    'a A b B c d e E f F g G o 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 width* is the number of field width units a
@@ -206,20 +206,22 @@ string s5 = format("{:6d}", c);             // value of s5 is "\ \ \ 120"
 string s6 = format("{:6}", true);           // value of s6 is "true\ \ "
 string s7 = format("{:*<6.3}", "123456");   // value of s7 is "123***"
 string s8 = format("{:02}", 1234);          // value of s8 is "1234"
 string s9 = format("{:*<}", "12");          // value of s9 is "12"
 string sA = format("{:*<6}", "12345678");   // value of sA is "12345678"
 ```
 — *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: Meaning of align options** <a id="format.align">[format.align]</a>
@@ -271,15 +273,16 @@ 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` 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*:
 ``` cpp
 char c = 120;
@@ -294,13 +297,13 @@ string s4 = format("{:06}", inf);       // value of s4 is "\ \ \ inf" (0 has no
 The *width* option specifies the minimum field width. If the *width*
 option is absent, the minimum field width is `0`.
 If `{ \opt{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. If the corresponding formatting argument is not of standard
-signed or unsigned integer type, or 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.
@@ -309,25 +312,25 @@ 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 5*:
-This is the case for Windows[^2]
--based and 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"` or
-  `East_Asian_Width="F"` Derived Extracted 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.
@@ -417,13 +420,13 @@ 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]]. |
 | % `?`                          | Copies the escaped character [[format.string.escaped]] to the output.                                      |
 The available `bool` presentation types are specified in
 [[format.type.bool]].
@@ -469,7 +472,8 @@ are specified in [[format.type.ptr]].
 **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` inserted immediately before the output of `to_chars`; otherwise, implementation-defined. |

 ### Format string <a id="format.string">[[format.string]]</a>
+#### 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
     ':' format-spec
 ```
 ``` bnf
 format-spec
+    as specified by the formatter specialization for the argument type; cannot start with '}'
 ```
 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
 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*]
     '.' '{' arg-idₒₚₜ '}'
 ```
 ``` bnf
 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 width* is the number of field width units a
 string s6 = format("{:6}", true);           // value of s6 is "true\ \ "
 string s7 = format("{:*<6.3}", "123456");   // value of s7 is "123***"
 string s8 = format("{:02}", 1234);          // value of s8 is "1234"
 string s9 = format("{:*<}", "12");          // value of s9 is "12"
 string sA = format("{:*<6}", "12345678");   // value of sA is "12345678"
+string sB = format("{:\importexample[-2pt]{example_05}\kern0.75pt^6}", "x");         // value of sB is "\importexample[-2pt]{example_05\importexample[-2pt]{example_05}x\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}"}
+string sC = format("{:*^6}", "\importexample[-2pt]{example_05}\kern0.75pt\importexample[-2pt]{example_05}\kern0.75pt\importexample[-2pt]{example_05}\kern0.75pt");     // value of sC is "\importexample[-2pt]{example_05\importexample[-2pt]{example_05}\importexample[-2pt]{example_05}"}
 ```
 — *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: Meaning of align options** <a id="format.align">[format.align]</a>
 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*:
 ``` cpp
 char c = 120;
 The *width* option specifies the minimum field width. If the *width*
 option is absent, the minimum field width is `0`.
 If `{ \opt{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.
 should use either UTF-8, UTF-16, or UTF-32, on platforms capable of
 displaying Unicode text in a terminal.
 [*Note 5*:
+This is the case for Windows®-based[^25]
+and 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"` or
+  `East_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.
 [[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]] with `value` converted to the unsigned version of the underlying type. |
 | % `?`                          | Copies the escaped character [[format.string.escaped]] to the output.                                      |
 The available `bool` presentation types are specified in
 [[format.type.bool]].
 **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` inserted immediately before the output of `to_chars`; otherwise, implementation-defined. |
+| `P`       | The same as `p`, except that it uses uppercase letters for digits above `9` and the base prefix is `0X`.                                                                                                                                 |

Diff to HTML by rtfpessoa