From Jason Turner

[time.format]

C++17 → C++20 32.9 KB 285 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpf6azch3p/{from.md → to.md} +282 -0
tmp/tmpf6azch3p/{from.md → to.md} RENAMED
@@ -0,0 +1,282 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ## Formatting <a id="time.format">[[time.format]]</a>
2
+
3
+ Each `formatter` [[format.formatter]] specialization in the chrono
4
+ library [[time.syn]] meets the requirements [[formatter.requirements]].
5
+ 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
17
+ chrono-specs conversion-spec
18
+ chrono-specs literal-char
19
+ ```
20
+
21
+ ``` bnf
22
+ literal-char
23
+ any character other than \{, \}, or \%
24
+ ```
25
+
26
+ ``` bnf
27
+ conversion-spec
28
+ '%' modifierₒₚₜ type
29
+ ```
30
+
31
+ ``` bnf
32
+ modifier one of
33
+ 'E O'
34
+ ```
35
+
36
+ ``` bnf
37
+ type one of
38
+ 'a A b B c C d D e F g G h H I j m M n'
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
62
+ before the replacement of the initial conversion specifier.
63
+
64
+ [*Example 1*:
65
+
66
+ ``` cpp
67
+ cout << format("{:%T}", -10'000s); // prints: -02:46:40
68
+ cout << format("{:%H:%M:%S}", -10'000s); // prints: -02:46:40
69
+ cout << format("minutes {:%M, hours %H, seconds %S}", -10'000s);
70
+ // prints: minutes -46, hours 02, seconds 40
71
+ ```
72
+
73
+ — *end example*]
74
+
75
+ Unless explicitly requested, the result of formatting a chrono type does
76
+ not contain time zone abbreviation and time zone offset information. If
77
+ the information is available, the conversion specifiers `%Z` and `%z`
78
+ will format this information (respectively).
79
+
80
+ [*Note 1*: If the information is not available and a `%Z` or `%z`
81
+ conversion specifier appears in the *chrono-format-spec*, an exception
82
+ of type `format_error` is thrown, as described above. — *end note*]
83
+
84
+ 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
+
96
+ | Specifier | Replacement |
97
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
+ | `%a` | The locale's abbreviated weekday name. If the value does not contain a valid weekday, an exception of type `format_error` is thrown. |
99
+ | `%A` | The locale's full weekday name. If the value does not contain a valid weekday, an exception of type `format_error` is thrown. |
100
+ | `%b` | The locale's abbreviated month name. If the value does not contain a valid month, an exception of type `format_error` is thrown. |
101
+ | `%B` | The locale's full month name. If the value does not contain a valid month, an exception of type `format_error` is thrown. |
102
+ | `%c` | The locale's date and time representation. The modified command `%Ec` produces the locale's alternate date and time representation. |
103
+ | `%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. |
104
+ | `%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. |
105
+ | `%D` | Equivalent to `%m/%d/%y`. |
106
+ | `%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. |
107
+ | `%F` | Equivalent to `%Y-%m-%d`. |
108
+ | `%g` | The last two decimal digits of the ISO week-based year. If the result is a single digit it is prefixed by `0`. |
109
+ | `%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. |
110
+ | `%h` | Equivalent to `%b`. |
111
+ | `%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. |
112
+ | `%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. |
113
+ | `%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. |
114
+ | `%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. |
115
+ | `%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. |
116
+ | `%n` | A new-line character. |
117
+ | `%p` | The locale's equivalent of the AM/PM designations associated with a 12-hour clock. |
118
+ | `%q` | The duration's unit suffix as specified in [[time.duration.io]]. |
119
+ | `%Q` | The duration's numeric value (as if extracted via `.count()`). |
120
+ | `%r` | The locale's 12-hour clock time. |
121
+ | `%R` | Equivalent to `%H:%M`. |
122
+ | `%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. |
123
+ | `%t` | A horizontal-tab character. |
124
+ | `%T` | Equivalent to `%H:%M:%S`. |
125
+ | `%u` | The ISO weekday as a decimal number (`1`-`7`), where Monday is `1`. The modified command `%Ou` produces the locale's alternative representation. |
126
+ | `%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. |
127
+ | `%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. |
128
+ | `%w` | The weekday as a decimal number (`0`-`6`), where Sunday is `0`. The modified command `%Ow` produces the locale's alternative representation. |
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"
148
+ ```
149
+
150
+ — *end example*]
151
+
152
+ ``` cpp
153
+ template<class Duration, class charT>
154
+ struct formatter<chrono::sys_time<Duration>, charT>;
155
+ ```
156
+
157
+ *Remarks:* If `%Z` is used, it is replaced with
158
+ *`STATICALLY-WIDEN`*`<charT>("UTC")`. If `%z` (or a modified variant of
159
+ `%z`) is used, an offset of `0min` is formatted.
160
+
161
+ ``` cpp
162
+ template<class Duration, class charT>
163
+ struct formatter<chrono::utc_time<Duration>, charT>;
164
+ ```
165
+
166
+ *Remarks:* If `%Z` is used, it is replaced with
167
+ *`STATICALLY-WIDEN`*`<charT>("UTC")`. If `%z` (or a modified variant of
168
+ `%z`) is used, an offset of `0min` is formatted. If the argument
169
+ represents a time during a positive leap second insertion, and if a
170
+ seconds field is formatted, the integral portion of that format is
171
+ *`STATICALLY-WIDEN`*`<charT>("60")`.
172
+
173
+ ``` cpp
174
+ template<class Duration, class charT>
175
+ struct formatter<chrono::tai_time<Duration>, charT>;
176
+ ```
177
+
178
+ *Remarks:* If `%Z` is used, it is replaced with
179
+ *`STATICALLY-WIDEN`*`<charT>("TAI")`. If `%z` (or a modified variant of
180
+ `%z`) is used, an offset of `0min` is formatted. The date and time
181
+ formatted are equivalent to those formatted by a `sys_time` initialized
182
+ with
183
+
184
+ ``` cpp
185
+ sys_time<Duration>{tp.time_since_epoch()} -
186
+ (sys_days{1970y/January/1} - sys_days{1958y/January/1})
187
+ ```
188
+
189
+ ``` cpp
190
+ template<class Duration, class charT>
191
+ struct formatter<chrono::gps_time<Duration>, charT>;
192
+ ```
193
+
194
+ *Remarks:* If `%Z` is used, it is replaced with
195
+ *`STATICALLY-WIDEN`*`<charT>("GPS")`. If `%z` (or a modified variant of
196
+ `%z`) is used, an offset of `0min` is formatted. The date and time
197
+ formatted are equivalent to those formatted by a `sys_time` initialized
198
+ with
199
+
200
+ ``` cpp
201
+ sys_time<Duration>{tp.time_since_epoch()} +
202
+ (sys_days{1980y/January/Sunday[1]} - sys_days{1970y/January/1})
203
+ ```
204
+
205
+ ``` cpp
206
+ template<class Duration, class charT>
207
+ struct formatter<chrono::file_time<Duration>, charT>;
208
+ ```
209
+
210
+ *Remarks:* If `%Z` is used, it is replaced with
211
+ *`STATICALLY-WIDEN`*`<charT>("UTC")`. If `%z` (or a modified variant of
212
+ `%z`) is used, an offset of `0min` is formatted. The date and time
213
+ formatted are equivalent to those formatted by a `sys_time` initialized
214
+ with `clock_cast<system_clock>(t)`, or by a `utc_time` initialized with
215
+ `clock_cast<utc_clock>(t)`, where `t` is the first argument to `format`.
216
+
217
+ ``` cpp
218
+ template<class Duration, class charT>
219
+ struct formatter<chrono::local_time<Duration>, charT>;
220
+ ```
221
+
222
+ *Remarks:* If `%Z`, `%z`, or a modified version of `%z` is used, an
223
+ exception of type `format_error` is thrown.
224
+
225
+ ``` cpp
226
+ template<class Duration> struct local-time-format-t { // exposition only
227
+ local_time<Duration> time; // exposition only
228
+ const string* abbrev; // exposition only
229
+ const seconds* offset_sec; // exposition only
230
+ };
231
+ ```
232
+
233
+ ``` cpp
234
+ template<class Duration>
235
+ local-time-format-t<Duration>
236
+ local_time_format(local_time<Duration> time, const string* abbrev = nullptr,
237
+ const seconds* offset_sec = nullptr);
238
+ ```
239
+
240
+ *Returns:* `{time, abbrev, offset_sec}`.
241
+
242
+ ``` cpp
243
+ template<class Duration, class charT>
244
+ struct formatter<chrono::local-time-format-t<Duration>, charT>;
245
+ ```
246
+
247
+ Let `f` be a *`local-time-format-t`*`<Duration>` object passed to
248
+ `formatter::format`.
249
+
250
+ *Remarks:* If `%Z` is used, it is replaced with `*f.abbrev` if
251
+ `f.abbrev` is not a null pointer value. If `%Z` is used and `f.abbrev`
252
+ is a null pointer value, an exception of type `format_error` is thrown.
253
+ If `%z` (or a modified variant of `%z`) is used, it is formatted with
254
+ the value of `*f.offset_sec` if `f.offset_sec` is not a null pointer
255
+ value. If `%z` (or a modified variant of `%z`) is used and
256
+ `f.offset_sec` is a null pointer value, then an exception of type
257
+ `format_error` is thrown.
258
+
259
+ ``` cpp
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
278
+ sys_info info = tp.get_info();
279
+ return formatter<chrono::local-time-format-t<Duration>, charT>::
280
+ format({tp.get_local_time(), &info.abbrev, &info.offset}, ctx);
281
+ ```
282
+