From Jason Turner

[time.format]

C++23 → Trunk 28.9 KB 76 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpqloim0n9/{from.md → to.md} +45 -24
tmp/tmpqloim0n9/{from.md → to.md} RENAMED
@@ -56,11 +56,11 @@ function, defined as
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
@@ -115,16 +115,16 @@ day elapsed since midnight.
115
  | `%C` | The year divided by 100 using floored division. If the result is a single decimal digit, it is prefixed with `0`. The modified command `%EC` produces the locale's alternative representation of the century. |
116
  | `%d` | The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with `0`. The modified command `%Od` produces the locale's alternative representation. |
117
  | `%D` | Equivalent to `%m/%d/%y`. |
118
  | `%e` | The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with a space. The modified command `%Oe` produces the locale's alternative representation. |
119
  | `%F` | Equivalent to `%Y-%m-%d`. |
120
- | `%g` | The last two decimal digits of the ISO week-based year. If the result is a single digit it is prefixed by `0`. |
121
- | `%G` | The ISO week-based year as a decimal number. If the result is less than four digits it is left-padded with `0` to four digits. |
122
  | `%h` | Equivalent to `%b`. |
123
  | `%H` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OH` produces the locale's alternative representation. |
124
  | `%I` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OI` produces the locale's alternative representation. |
125
- | `%j` | If the type being formatted is a specialization of `duration`, the decimal number of `days` without padding. Otherwise, the day of the year as a decimal number. Jan 1 is `001`. If the result is less than three digits, it is left-padded with `0` to three digits. |
126
  | `%m` | The month as a decimal number. Jan is `01`. If the result is a single digit, it is prefixed with `0`. The modified command `%Om` produces the locale's alternative representation. |
127
  | `%M` | The minute as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OM` produces the locale's alternative representation. |
128
  | `%n` | A new-line character. |
129
  | `%p` | The locale's equivalent of the AM/PM designations associated with a 12-hour clock. |
130
  | `%q` | The duration's unit suffix as specified in [[time.duration.io]]. |
@@ -132,38 +132,58 @@ day elapsed since midnight.
132
  | `%r` | The locale's 12-hour clock time. |
133
  | `%R` | Equivalent to `%H:%M`. |
134
  | `%S` | Seconds as a decimal number. If the number of seconds is less than `10`, the result is prefixed with `0`. If the precision of the input cannot be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format and a precision matching that of the precision of the input (or to a microseconds precision if the conversion to floating-point decimal seconds cannot be made within 18 fractional digits). The character for the decimal point is localized according to the locale. The modified command `%OS` produces the locale's alternative representation. |
135
  | `%t` | A horizontal-tab character. |
136
  | `%T` | Equivalent to `%H:%M:%S`. |
137
- | `%u` | The ISO weekday as a decimal number (`1`-`7`), where Monday is `1`. The modified command `%Ou` produces the locale's alternative representation. |
138
  | `%U` | The week number of the year as a decimal number. The first Sunday 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 `%OU` produces the locale's alternative representation. |
139
- | `%V` | The ISO week-based week number as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OV` produces the locale's alternative representation. |
140
  | `%w` | The weekday as a decimal number (`0`-`6`), where Sunday is `0`. The modified command `%Ow` produces the locale's alternative representation. |
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"
161
  ```
162
 
163
  — *end example*]
164
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
165
  ``` cpp
166
  template<class Duration, class charT>
167
  struct formatter<chrono::sys_time<Duration>, charT>;
168
  ```
169
 
@@ -258,23 +278,24 @@ template<class Duration, class charT>
258
  ```
259
 
260
  Let `f` be a *`local-time-format-t`*`<Duration>` object passed to
261
  `formatter::format`.
262
 
263
- *Remarks:* If `%Z` is used, it is replaced with `*f.abbrev` if
264
- `f.abbrev` is not a null pointer value. If `%Z` is used and `f.abbrev`
265
- is a null pointer value, an exception of type `format_error` is thrown.
266
- If `%z` (or a modified variant of `%z`) is used, it is formatted with
267
- the value of `*f.offset_sec` if `f.offset_sec` is not a null pointer
268
- value. If `%z` (or a modified variant of `%z`) is used and
269
- `f.offset_sec` is a null pointer value, then an exception of type
270
- `format_error` is thrown.
 
271
 
272
  ``` cpp
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
  ```
@@ -287,9 +308,9 @@ template<class FormatContext>
287
 
288
  *Effects:* Equivalent to:
289
 
290
  ``` cpp
291
  sys_info info = tp.get_info();
292
- return formatter<chrono::local-time-format-t<Duration>, charT>::
293
  format({tp.get_local_time(), &info.abbrev, &info.offset}, ctx);
294
  ```
295
 
 
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-1:2019 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
 
115
  | `%C` | The year divided by 100 using floored division. If the result is a single decimal digit, it is prefixed with `0`. The modified command `%EC` produces the locale's alternative representation of the century. |
116
  | `%d` | The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with `0`. The modified command `%Od` produces the locale's alternative representation. |
117
  | `%D` | Equivalent to `%m/%d/%y`. |
118
  | `%e` | The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with a space. The modified command `%Oe` produces the locale's alternative representation. |
119
  | `%F` | Equivalent to `%Y-%m-%d`. |
120
+ | `%g` | The last two decimal digits of the calendar year as specified in ISO 8601-1:2019 for the week calendar. If the result is a single digit it is prefixed by `0`. |
121
+ | `%G` | The calendar year as a decimal number, as specified in ISO 8601-1:2019 for the week calendar. If the result is less than four digits it is left-padded with `0` to four digits. |
122
  | `%h` | Equivalent to `%b`. |
123
  | `%H` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OH` produces the locale's alternative representation. |
124
  | `%I` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OI` produces the locale's alternative representation. |
125
+ | `%j` | If the type being formatted is a specialization of `duration`, the decimal number of `days` without padding. Otherwise, the day of the year as a decimal number. January 1 is `001`. If the result is less than three digits, it is left-padded with `0` to three digits. |
126
  | `%m` | The month as a decimal number. Jan is `01`. If the result is a single digit, it is prefixed with `0`. The modified command `%Om` produces the locale's alternative representation. |
127
  | `%M` | The minute as a decimal number. If the result is a single digit, it is prefixed with `0`. The modified command `%OM` produces the locale's alternative representation. |
128
  | `%n` | A new-line character. |
129
  | `%p` | The locale's equivalent of the AM/PM designations associated with a 12-hour clock. |
130
  | `%q` | The duration's unit suffix as specified in [[time.duration.io]]. |
 
132
  | `%r` | The locale's 12-hour clock time. |
133
  | `%R` | Equivalent to `%H:%M`. |
134
  | `%S` | Seconds as a decimal number. If the number of seconds is less than `10`, the result is prefixed with `0`. If the precision of the input cannot be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format and a precision matching that of the precision of the input (or to a microseconds precision if the conversion to floating-point decimal seconds cannot be made within 18 fractional digits). The character for the decimal point is localized according to the locale. The modified command `%OS` produces the locale's alternative representation. |
135
  | `%t` | A horizontal-tab character. |
136
  | `%T` | Equivalent to `%H:%M:%S`. |
137
+ | `%u` | The calendar day of week as a decimal number (`1`-`7`), as specified in ISO 8601-1:2019, where Monday is `1`. The modified command `%Ou` produces the locale's alternative representation. |
138
  | `%U` | The week number of the year as a decimal number. The first Sunday 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 `%OU` produces the locale's alternative representation. |
139
+ | `%V` | The calendar week of year as a decimal number, as specified in ISO 8601-1:2019 for the week calendar. If the result is a single digit, it is prefixed with `0`. The modified command `%OV` produces the locale's alternative representation. |
140
  | `%w` | The weekday as a decimal number (`0`-`6`), where Sunday is `0`. The modified command `%Ow` produces the locale's alternative representation. |
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 as specified in ISO 8601-1:2019, 5.3.4.1. 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
+ Unless otherwise specified, if the *chrono-specs* is omitted, the chrono
152
+ object is formatted as if by streaming it to
153
+ `basic_ostringstream<charT> os` with the formatting locale imbued and
154
+ copying `os.str()` through the output iterator of the context with
155
+ additional padding and adjustments as specified by the format
156
+ specifiers.
157
 
158
  [*Example 3*:
159
 
160
  ``` cpp
161
  string s = format("{:=>8}", 42ms); // value of s is "====42ms"
162
  ```
163
 
164
  — *end example*]
165
 
166
+ For `chrono::duration` the library only provides the following
167
+ specialization of `enable_nonlocking_formatter_optimization`:
168
+
169
+ ``` cpp
170
+ template<class Rep, class Period>
171
+ constexpr bool enable_nonlocking_formatter_optimization<
172
+ chrono::duration<Rep, Period>> =
173
+ enable_nonlocking_formatter_optimization<Rep>;
174
+ ```
175
+
176
+ For `chrono::zoned_time` the library only provides the following
177
+ specialization of `enable_nonlocking_formatter_optimization`:
178
+
179
+ ``` cpp
180
+ template<class Duration>
181
+ constexpr bool enable_nonlocking_formatter_optimization<
182
+ chrono::zoned_time<Duration, const std::chrono::time_zone*>> = true;
183
+ ```
184
+
185
  ``` cpp
186
  template<class Duration, class charT>
187
  struct formatter<chrono::sys_time<Duration>, charT>;
188
  ```
189
 
 
278
  ```
279
 
280
  Let `f` be a *`local-time-format-t`*`<Duration>` object passed to
281
  `formatter::format`.
282
 
283
+ *Remarks:* If the *chrono-specs* is omitted, the result is equivalent to
284
+ using `%F %T %Z` as the *chrono-specs*. If `%Z` is used, it is replaced
285
+ with `*f.abbrev` if `f.abbrev` is not a null pointer value. If `%Z` is
286
+ used and `f.abbrev` is a null pointer value, an exception of type
287
+ `format_error` is thrown. If `%z` (or a modified variant of `%z`) is
288
+ used, it is formatted with the value of `*f.offset_sec` if
289
+ `f.offset_sec` is not a null pointer value. If `%z` (or a modified
290
+ variant of `%z`) is used and `f.offset_sec` is a null pointer value,
291
+ then an exception of type `format_error` is thrown.
292
 
293
  ``` cpp
294
  template<class Duration, class TimeZonePtr, class charT>
295
  struct formatter<chrono::zoned_time<Duration, TimeZonePtr>, charT>
296
+ : formatter<chrono::local-time-format-t<common_type_t<Duration, seconds>>, charT> {
297
  template<class FormatContext>
298
  typename FormatContext::iterator
299
  format(const chrono::zoned_time<Duration, TimeZonePtr>& tp, FormatContext& ctx) const;
300
  };
301
  ```
 
308
 
309
  *Effects:* Equivalent to:
310
 
311
  ``` cpp
312
  sys_info info = tp.get_info();
313
+ return formatter<chrono::local-time-format-t<common_type_t<Duration, seconds>>, charT>::
314
  format({tp.get_local_time(), &info.abbrev, &info.offset}, ctx);
315
  ```
316