From Jason Turner

[time.format]

C++20 → C++23 10.6 KB 58 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp6bb1v33w/{from.md → to.md} +32 -19
tmp/tmp6bb1v33w/{from.md → to.md} RENAMED
@@ -6,11 +6,11 @@ The `parse` member functions of these formatters interpret the format
6
  specification as a *chrono-format-spec* according to the following
7
  syntax:
8
 
9
  ``` bnf
10
  chrono-format-spec
11
- fill-and-alignₒₚₜ widthₒₚₜ precisionₒₚₜ chrono-specsₒₚₜ
12
  ```
13
 
14
  ``` bnf
15
  chrono-specs
16
  conversion-spec
@@ -39,23 +39,35 @@ type one of
39
  'p q Q r R S t T u U V w W x X y Y z Z %'
40
  ```
41
 
42
  The productions *fill-and-align*, *width*, and *precision* are described
43
  in [[format.string]]. Giving a *precision* specification in the
44
- *chrono-format-spec* is valid only for `std::chrono::duration` types
45
- where the representation type `Rep` is a floating-point type. For all
46
- other `Rep` types, an exception of type `format_error` is thrown if the
47
- *chrono-format-spec* contains a *precision* specification. All ordinary
48
- multibyte characters represented by *literal-char* are copied unchanged
49
- to the output.
 
 
 
 
 
 
 
 
50
 
51
  Each conversion specifier *conversion-spec* is replaced by appropriate
52
- characters as described in [[time.format.spec]]. Some of the conversion
53
- specifiers depend on the locale that is passed to the formatting
54
- function if the latter takes one, or the global locale otherwise. If the
55
- formatted object does not contain the information the conversion
56
- specifier refers to, an exception of type `format_error` is thrown.
 
 
 
 
57
 
58
  The result of formatting a `std::chrono::duration` instance holding a
59
  negative value, or an `hh_mm_ss` object `h` for which `h.is_negative()`
60
  is `true`, is equivalent to the output of the corresponding positive
61
  value, with a `STATICALLY-WIDEN<charT>("-")` character sequence placed
@@ -85,11 +97,11 @@ If the type being formatted does not contain the information that the
85
  format flag needs, an exception of type `format_error` is thrown.
86
 
87
  [*Example 2*: A `duration` does not contain enough information to
88
  format as a `weekday`. — *end example*]
89
 
90
- However, if a flag refers to a “time of day” (e.g. `%H`, `%I`, `%p`,
91
  etc.), then a specialization of `duration` is interpreted as the time of
92
  day elapsed since midnight.
93
 
94
  **Table: Meaning of conversion specifiers** <a id="time.format.spec">[time.format.spec]</a>
95
 
@@ -129,19 +141,20 @@ day elapsed since midnight.
129
  | `%W` | The week number of the year as a decimal number. The first Monday of the year is the first day of week `01`. Days of the same year prior to that are in week `00`. If the result is a single digit, it is prefixed with `0`. The modified command `%OW` produces the locale's alternative representation. |
130
  | `%x` | The locale's date representation. The modified command `%Ex` produces the locale's alternate date representation. |
131
  | `%X` | The locale's time representation. The modified command `%EX` produces the locale's alternate time representation. |
132
  | `%y` | The last two decimal digits of the year. If the result is a single digit it is prefixed by `0`. The modified command `%Oy` produces the locale's alternative representation. The modified command `%Ey` produces the locale's alternative representation of offset from `%EC` (year only). |
133
  | `%Y` | The year as a decimal number. If the result is less than four digits it is left-padded with `0` to four digits. The modified command `%EY` produces the locale's alternative full year representation. |
134
- | `%z` | The offset from UTC in the ISO 8601 format. For example `-0430` refers to 4 hours 30 minutes behind UTC. If the offset is zero, `+0000` is used. The modified commands `%Ez` and `%Oz` insert a `:` between the hours and minutes: `-04:30`. If the offset information is not available, an exception of type `format_error` is thrown. |
135
  | `%Z` | The time zone abbreviation. If the time zone abbreviation is not available, an exception of type `format_error` is thrown. |
136
  | `%%` | A `%` character. |
137
 
138
 
139
  If the *chrono-specs* is omitted, the chrono object is formatted as if
140
- by streaming it to `std::ostringstream os` and copying `os.str()`
141
- through the output iterator of the context with additional padding and
142
- adjustments as specified by the format specifiers.
 
143
 
144
  [*Example 3*:
145
 
146
  ``` cpp
147
  string s = format("{:=>8}", 42ms); // value of s is "====42ms"
@@ -260,18 +273,18 @@ value. If `%z` (or a modified variant of `%z`) is used and
260
  template<class Duration, class TimeZonePtr, class charT>
261
  struct formatter<chrono::zoned_time<Duration, TimeZonePtr>, charT>
262
  : formatter<chrono::local-time-format-t<Duration>, charT> {
263
  template<class FormatContext>
264
  typename FormatContext::iterator
265
- format(const chrono::zoned_time<Duration, TimeZonePtr>& tp, FormatContext& ctx);
266
  };
267
  ```
268
 
269
  ``` cpp
270
  template<class FormatContext>
271
  typename FormatContext::iterator
272
- format(const chrono::zoned_time<Duration, TimeZonePtr>& tp, FormatContext& ctx);
273
  ```
274
 
275
  *Effects:* Equivalent to:
276
 
277
  ``` cpp
 
6
  specification as a *chrono-format-spec* according to the following
7
  syntax:
8
 
9
  ``` bnf
10
  chrono-format-spec
11
+ fill-and-alignₒₚₜ widthₒₚₜ precisionₒₚₜ 'L'ₒₚₜ chrono-specsₒₚₜ
12
  ```
13
 
14
  ``` bnf
15
  chrono-specs
16
  conversion-spec
 
39
  'p q Q r R S t T u U V w W x X y Y z Z %'
40
  ```
41
 
42
  The productions *fill-and-align*, *width*, and *precision* are described
43
  in [[format.string]]. Giving a *precision* specification in the
44
+ *chrono-format-spec* is valid only for types that are specializations of
45
+ `std::chrono::duration` for which the nested *typedef-name* `rep`
46
+ denotes a floating-point type. For all other types, an exception of type
47
+ `format_error` is thrown if the *chrono-format-spec* contains a
48
+ *precision* specification. All ordinary multibyte characters represented
49
+ by *literal-char* are copied unchanged to the output.
50
+
51
+ A *formatting locale* is an instance of `locale` used by a formatting
52
+ function, defined as
53
+
54
+ - the `"C"` locale if the `L` option is not present in
55
+ *chrono-format-spec*, otherwise
56
+ - the locale passed to the formatting function if any, otherwise
57
+ - the global locale.
58
 
59
  Each conversion specifier *conversion-spec* is replaced by appropriate
60
+ characters as described in [[time.format.spec]]; the formats specified
61
+ in ISO 8601:2004 shall be used where so described. Some of the
62
+ conversion specifiers depend on the formatting locale. If the string
63
+ literal encoding is a Unicode encoding form and the locale is among an
64
+ *implementation-defined* set of locales, each replacement that depends
65
+ on the locale is performed as if the replacement character sequence is
66
+ converted to the string literal encoding. If the formatted object does
67
+ not contain the information the conversion specifier refers to, an
68
+ exception of type `format_error` is thrown.
69
 
70
  The result of formatting a `std::chrono::duration` instance holding a
71
  negative value, or an `hh_mm_ss` object `h` for which `h.is_negative()`
72
  is `true`, is equivalent to the output of the corresponding positive
73
  value, with a `STATICALLY-WIDEN<charT>("-")` character sequence placed
 
97
  format flag needs, an exception of type `format_error` is thrown.
98
 
99
  [*Example 2*: A `duration` does not contain enough information to
100
  format as a `weekday`. — *end example*]
101
 
102
+ However, if a flag refers to a “time of day” (e.g., `%H`, `%I`, `%p`,
103
  etc.), then a specialization of `duration` is interpreted as the time of
104
  day elapsed since midnight.
105
 
106
  **Table: Meaning of conversion specifiers** <a id="time.format.spec">[time.format.spec]</a>
107
 
 
141
  | `%W` | The week number of the year as a decimal number. The first Monday of the year is the first day of week `01`. Days of the same year prior to that are in week `00`. If the result is a single digit, it is prefixed with `0`. The modified command `%OW` produces the locale's alternative representation. |
142
  | `%x` | The locale's date representation. The modified command `%Ex` produces the locale's alternate date representation. |
143
  | `%X` | The locale's time representation. The modified command `%EX` produces the locale's alternate time representation. |
144
  | `%y` | The last two decimal digits of the year. If the result is a single digit it is prefixed by `0`. The modified command `%Oy` produces the locale's alternative representation. The modified command `%Ey` produces the locale's alternative representation of offset from `%EC` (year only). |
145
  | `%Y` | The year as a decimal number. If the result is less than four digits it is left-padded with `0` to four digits. The modified command `%EY` produces the locale's alternative full year representation. |
146
+ | `%z` | The offset from UTC in the ISO 8601:2004 format. For example `-0430` refers to 4 hours 30 minutes behind UTC. If the offset is zero, `+0000` is used. The modified commands `%Ez` and `%Oz` insert a `:` between the hours and minutes: `-04:30`. If the offset information is not available, an exception of type `format_error` is thrown. |
147
  | `%Z` | The time zone abbreviation. If the time zone abbreviation is not available, an exception of type `format_error` is thrown. |
148
  | `%%` | A `%` character. |
149
 
150
 
151
  If the *chrono-specs* is omitted, the chrono object is formatted as if
152
+ by streaming it to `basic_ostringstream<charT> os` with the formatting
153
+ locale imbued and copying `os.str()` through the output iterator of the
154
+ context with additional padding and adjustments as specified by the
155
+ format specifiers.
156
 
157
  [*Example 3*:
158
 
159
  ``` cpp
160
  string s = format("{:=>8}", 42ms); // value of s is "====42ms"
 
273
  template<class Duration, class TimeZonePtr, class charT>
274
  struct formatter<chrono::zoned_time<Duration, TimeZonePtr>, charT>
275
  : formatter<chrono::local-time-format-t<Duration>, charT> {
276
  template<class FormatContext>
277
  typename FormatContext::iterator
278
+ format(const chrono::zoned_time<Duration, TimeZonePtr>& tp, FormatContext& ctx) const;
279
  };
280
  ```
281
 
282
  ``` cpp
283
  template<class FormatContext>
284
  typename FormatContext::iterator
285
+ format(const chrono::zoned_time<Duration, TimeZonePtr>& tp, FormatContext& ctx) const;
286
  ```
287
 
288
  *Effects:* Equivalent to:
289
 
290
  ``` cpp