From Jason Turner

[time.hms]

C++17 → C++20 6.2 KB 203 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/tmp9hfq_onm/{from.md → to.md} +200 -0
tmp/tmp9hfq_onm/{from.md → to.md} RENAMED
@@ -0,0 +1,200 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ## Class template `hh_mm_ss` <a id="time.hms">[[time.hms]]</a>
2
+
3
+ ### Overview <a id="time.hms.overview">[[time.hms.overview]]</a>
4
+
5
+ ``` cpp
6
+ namespace std::chrono {
7
+ template<class Duration> class hh_mm_ss {
8
+ public:
9
+ static constexpr unsigned fractional_width = see below;
10
+ using precision = see below;
11
+
12
+ constexpr hh_mm_ss() noexcept : hh_mm_ss{Duration::zero()} {}
13
+ constexpr explicit hh_mm_ss(Duration d);
14
+
15
+ constexpr bool is_negative() const noexcept;
16
+ constexpr chrono::hours hours() const noexcept;
17
+ constexpr chrono::minutes minutes() const noexcept;
18
+ constexpr chrono::seconds seconds() const noexcept;
19
+ constexpr precision subseconds() const noexcept;
20
+
21
+ constexpr explicit operator precision() const noexcept;
22
+ constexpr precision to_duration() const noexcept;
23
+
24
+ private:
25
+ bool is_neg; // exposition only
26
+ chrono::hours h; // exposition only
27
+ chrono::minutes m; // exposition only
28
+ chrono::seconds s; // exposition only
29
+ precision ss; // exposition only
30
+ };
31
+ }
32
+ ```
33
+
34
+ The `hh_mm_ss` class template splits a `duration` into a multi-field
35
+ time structure *hours*:*minutes*:*seconds* and possibly *subseconds*,
36
+ where *subseconds* will be a duration unit based on a non-positive power
37
+ of 10. The `Duration` template parameter dictates the precision to which
38
+ the time is split. A `hh_mm_ss` models negative durations with a
39
+ distinct `is_negative` getter that returns `true` when the input
40
+ duration is negative. The individual duration fields always return
41
+ non-negative durations even when `is_negative()` indicates the structure
42
+ is representing a negative duration.
43
+
44
+ If `Duration` is not an instance of `duration`, the program is
45
+ ill-formed.
46
+
47
+ ### Members <a id="time.hms.members">[[time.hms.members]]</a>
48
+
49
+ ``` cpp
50
+ static constexpr unsigned fractional_width = see below;
51
+ ```
52
+
53
+ `fractional_width` is the number of fractional decimal digits
54
+ represented by `precision`. `fractional_width` has the value of the
55
+ smallest possible integer in the range \[`0`, `18`\] such that
56
+ `precision` will exactly represent all values of `Duration`. If no such
57
+ value of `fractional_width` exists, then `fractional_width` is 6.
58
+
59
+ [*Example 1*:
60
+
61
+ See  [[time.hms.width]] for some durations, the resulting
62
+ `fractional_width`, and the formatted fractional second output of
63
+ `Duration{1}`.
64
+
65
+ **Table: Examples for `fractional_width`** <a id="time.hms.width">[time.hms.width]</a>
66
+
67
+ | | | |
68
+ | --------------------------------- | --- | ------------- |
69
+ | `hours`, `minutes`, and `seconds` | `0` | |
70
+ | `milliseconds` | `3` | `0.001` |
71
+ | `microseconds` | `6` | `0.000001` |
72
+ | `nanoseconds` | `9` | `0.000000001` |
73
+ | `duration<int, ratio<1, 2>>` | `1` | `0.5` |
74
+ | `duration<int, ratio<1, 3>>` | `6` | `0.333333` |
75
+ | `duration<int, ratio<1, 4>>` | `2` | `0.25` |
76
+ | `duration<int, ratio<1, 5>>` | `1` | `0.2` |
77
+ | `duration<int, ratio<1, 6>>` | `6` | `0.166666` |
78
+ | `duration<int, ratio<1, 7>>` | `6` | `0.142857` |
79
+ | `duration<int, ratio<1, 8>>` | `3` | `0.125` |
80
+ | `duration<int, ratio<1, 9>>` | `6` | `0.111111` |
81
+ | `duration<int, ratio<1, 10>>` | `1` | `0.1` |
82
+ | `duration<int, ratio<756, 625>>` | `4` | `0.2096` |
83
+
84
+
85
+ — *end example*]
86
+
87
+ ``` cpp
88
+ using precision = see below;
89
+ ```
90
+
91
+ `precision` is
92
+
93
+ ``` cpp
94
+ duration<common_type_t<Duration::rep, seconds::rep>, ratio<1, $10^fractional_width$>>
95
+ ```
96
+
97
+ ``` cpp
98
+ constexpr explicit hh_mm_ss(Duration d);
99
+ ```
100
+
101
+ *Effects:* Constructs an object of type `hh_mm_ss` which represents the
102
+ `Duration d` with precision `precision`.
103
+
104
+ - Initializes `is_neg` with `d < Duration::zero()`.
105
+ - Initializes `h` with `duration_cast<chrono::hours>(abs(d))`.
106
+ - Initializes `m` with
107
+ `duration_cast<chrono::minutes>(abs(d) - hours())`.
108
+ - Initializes `s` with
109
+ `duration_cast<chrono::seconds>(abs(d) - hours() - minutes())`.
110
+ - If `treat_as_floating_point_v<precision::rep>` is `true`, initializes
111
+ `ss` with `abs(d) - hours() - minutes() - seconds()`. Otherwise,
112
+ initializes `ss` with
113
+ `duration_cast<precision>(abs(d) - hours() - minutes() - seconds())`.
114
+
115
+ [*Note 1*: When `precision::rep` is integral and `precision::period` is
116
+ `ratio<1>`, `subseconds()` always returns a value equal to
117
+ `0s`. — *end note*]
118
+
119
+ *Ensures:* If `treat_as_floating_point_v<precision::rep>` is `true`,
120
+ `to_duration()` returns `d`, otherwise `to_duration()` returns
121
+ `duration_cast<precision>(d)`.
122
+
123
+ ``` cpp
124
+ constexpr bool is_negative() const noexcept;
125
+ ```
126
+
127
+ *Returns:* `is_neg`.
128
+
129
+ ``` cpp
130
+ constexpr chrono::hours hours() const noexcept;
131
+ ```
132
+
133
+ *Returns:* `h`.
134
+
135
+ ``` cpp
136
+ constexpr chrono::minutes minutes() const noexcept;
137
+ ```
138
+
139
+ *Returns:* `m`.
140
+
141
+ ``` cpp
142
+ constexpr chrono::seconds seconds() const noexcept;
143
+ ```
144
+
145
+ *Returns:* `s`.
146
+
147
+ ``` cpp
148
+ constexpr precision subseconds() const noexcept;
149
+ ```
150
+
151
+ *Returns:* `ss`.
152
+
153
+ ``` cpp
154
+ constexpr precision to_duration() const noexcept;
155
+ ```
156
+
157
+ *Returns:* If `is_neg`, returns `-(h + m + s + ss)`, otherwise returns
158
+ `h + m + s + ss`.
159
+
160
+ ``` cpp
161
+ constexpr explicit operator precision() const noexcept;
162
+ ```
163
+
164
+ *Returns:* `to_duration()`.
165
+
166
+ ### Non-members <a id="time.hms.nonmembers">[[time.hms.nonmembers]]</a>
167
+
168
+ ``` cpp
169
+ template<class charT, class traits, class Duration>
170
+ basic_ostream<charT, traits>&
171
+ operator<<(basic_ostream<charT, traits>& os, const hh_mm_ss<Duration>& hms);
172
+ ```
173
+
174
+ *Effects:* Equivalent to:
175
+
176
+ ``` cpp
177
+ return os << format(os.getloc(), STATICALLY-WIDEN<charT>("{:%T}"), hms);
178
+ ```
179
+
180
+ [*Example 1*:
181
+
182
+ ``` cpp
183
+ for (auto ms : {-4083007ms, 4083007ms, 65745123ms}) {
184
+ hh_mm_ss hms{ms};
185
+ cout << hms << '\n';
186
+ }
187
+ cout << hh_mm_ss{65745s} << '\n';
188
+ ```
189
+
190
+ Produces the output (assuming the "C" locale):
191
+
192
+ ``` cpp
193
+ -01:08:03.007
194
+ 01:08:03.007
195
+ 18:15:45.123
196
+ 18:15:45
197
+ ```
198
+
199
+ — *end example*]
200
+