]>
Commit | Line | Data |
---|---|---|
0531ce1d | 1 | #![stable(feature = "duration_core", since = "1.25.0")] |
2c00a5a8 XL |
2 | |
3 | //! Temporal quantification. | |
4 | //! | |
5 | //! Example: | |
6 | //! | |
7 | //! ``` | |
8 | //! use std::time::Duration; | |
9 | //! | |
10 | //! let five_seconds = Duration::new(5, 0); | |
11 | //! // both declarations are equivalent | |
12 | //! assert_eq!(Duration::new(5, 0), Duration::from_secs(5)); | |
13 | //! ``` | |
1a4d82fc | 14 | |
f9f354fc | 15 | use crate::fmt; |
48663c56 | 16 | use crate::iter::Sum; |
60c5eb7d | 17 | use crate::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign}; |
d9579d0f AL |
18 | |
19 | const NANOS_PER_SEC: u32 = 1_000_000_000; | |
20 | const NANOS_PER_MILLI: u32 = 1_000_000; | |
ea8adc8c | 21 | const NANOS_PER_MICRO: u32 = 1_000; |
d9579d0f | 22 | const MILLIS_PER_SEC: u64 = 1_000; |
ea8adc8c | 23 | const MICROS_PER_SEC: u64 = 1_000_000; |
d9579d0f | 24 | |
32a655c1 | 25 | /// A `Duration` type to represent a span of time, typically used for system |
d9579d0f AL |
26 | /// timeouts. |
27 | /// | |
3b2f2976 | 28 | /// Each `Duration` is composed of a whole number of seconds and a fractional part |
9fa01778 | 29 | /// represented in nanoseconds. If the underlying system does not support |
3b2f2976 XL |
30 | /// nanosecond-level precision, APIs binding a system timeout will typically round up |
31 | /// the number of nanoseconds. | |
d9579d0f | 32 | /// |
3dfed10e XL |
33 | /// [`Duration`]s implement many common traits, including [`Add`], [`Sub`], and other |
34 | /// [`ops`] traits. It implements [`Default`] by returning a zero-length `Duration`. | |
32a655c1 | 35 | /// |
3dfed10e | 36 | /// [`ops`]: crate::ops |
d9579d0f AL |
37 | /// |
38 | /// # Examples | |
39 | /// | |
40 | /// ``` | |
d9579d0f AL |
41 | /// use std::time::Duration; |
42 | /// | |
43 | /// let five_seconds = Duration::new(5, 0); | |
44 | /// let five_seconds_and_five_nanos = five_seconds + Duration::new(0, 5); | |
45 | /// | |
c1a9b12d SL |
46 | /// assert_eq!(five_seconds_and_five_nanos.as_secs(), 5); |
47 | /// assert_eq!(five_seconds_and_five_nanos.subsec_nanos(), 5); | |
d9579d0f AL |
48 | /// |
49 | /// let ten_millis = Duration::from_millis(10); | |
50 | /// ``` | |
6a06907d XL |
51 | /// |
52 | /// # Formatting `Duration` values | |
53 | /// | |
54 | /// `Duration` intentionally does not have a `Display` impl, as there are a | |
55 | /// variety of ways to format spans of time for human readability. `Duration` | |
56 | /// provides a `Debug` impl that shows the full precision of the value. | |
57 | /// | |
58 | /// The `Debug` output uses the non-ASCII "µs" suffix for microseconds. If your | |
59 | /// program output may appear in contexts that cannot rely on full Unicode | |
60 | /// compatibility, you may wish to format `Duration` objects yourself or use a | |
61 | /// crate to do so. | |
0531ce1d | 62 | #[stable(feature = "duration", since = "1.3.0")] |
94b46f34 | 63 | #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] |
1a4d82fc | 64 | pub struct Duration { |
d9579d0f AL |
65 | secs: u64, |
66 | nanos: u32, // Always 0 <= nanos < NANOS_PER_SEC | |
1a4d82fc JJ |
67 | } |
68 | ||
1a4d82fc | 69 | impl Duration { |
9fa01778 XL |
70 | /// The duration of one second. |
71 | /// | |
72 | /// # Examples | |
73 | /// | |
74 | /// ``` | |
75 | /// #![feature(duration_constants)] | |
76 | /// use std::time::Duration; | |
77 | /// | |
78 | /// assert_eq!(Duration::SECOND, Duration::from_secs(1)); | |
79 | /// ``` | |
80 | #[unstable(feature = "duration_constants", issue = "57391")] | |
81 | pub const SECOND: Duration = Duration::from_secs(1); | |
82 | ||
83 | /// The duration of one millisecond. | |
84 | /// | |
85 | /// # Examples | |
86 | /// | |
87 | /// ``` | |
88 | /// #![feature(duration_constants)] | |
89 | /// use std::time::Duration; | |
90 | /// | |
91 | /// assert_eq!(Duration::MILLISECOND, Duration::from_millis(1)); | |
92 | /// ``` | |
93 | #[unstable(feature = "duration_constants", issue = "57391")] | |
94 | pub const MILLISECOND: Duration = Duration::from_millis(1); | |
95 | ||
96 | /// The duration of one microsecond. | |
97 | /// | |
98 | /// # Examples | |
99 | /// | |
100 | /// ``` | |
101 | /// #![feature(duration_constants)] | |
102 | /// use std::time::Duration; | |
103 | /// | |
104 | /// assert_eq!(Duration::MICROSECOND, Duration::from_micros(1)); | |
105 | /// ``` | |
106 | #[unstable(feature = "duration_constants", issue = "57391")] | |
107 | pub const MICROSECOND: Duration = Duration::from_micros(1); | |
108 | ||
109 | /// The duration of one nanosecond. | |
110 | /// | |
111 | /// # Examples | |
112 | /// | |
113 | /// ``` | |
114 | /// #![feature(duration_constants)] | |
115 | /// use std::time::Duration; | |
116 | /// | |
117 | /// assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1)); | |
118 | /// ``` | |
119 | #[unstable(feature = "duration_constants", issue = "57391")] | |
120 | pub const NANOSECOND: Duration = Duration::from_nanos(1); | |
121 | ||
29967ef6 | 122 | /// A duration of zero time. |
1b1a35ee XL |
123 | /// |
124 | /// # Examples | |
125 | /// | |
126 | /// ``` | |
29967ef6 | 127 | /// #![feature(duration_zero)] |
1b1a35ee XL |
128 | /// use std::time::Duration; |
129 | /// | |
29967ef6 XL |
130 | /// let duration = Duration::ZERO; |
131 | /// assert!(duration.is_zero()); | |
132 | /// assert_eq!(duration.as_nanos(), 0); | |
1b1a35ee | 133 | /// ``` |
29967ef6 XL |
134 | #[unstable(feature = "duration_zero", issue = "73544")] |
135 | pub const ZERO: Duration = Duration::from_nanos(0); | |
1b1a35ee XL |
136 | |
137 | /// The maximum duration. | |
138 | /// | |
139 | /// It is roughly equal to a duration of 584,942,417,355 years. | |
140 | /// | |
141 | /// # Examples | |
142 | /// | |
143 | /// ``` | |
144 | /// #![feature(duration_constants)] | |
145 | /// use std::time::Duration; | |
146 | /// | |
147 | /// assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1)); | |
148 | /// ``` | |
149 | #[unstable(feature = "duration_constants", issue = "57391")] | |
150 | pub const MAX: Duration = Duration::new(u64::MAX, NANOS_PER_SEC - 1); | |
151 | ||
3b2f2976 XL |
152 | /// Creates a new `Duration` from the specified number of whole seconds and |
153 | /// additional nanoseconds. | |
d9579d0f | 154 | /// |
3b2f2976 XL |
155 | /// If the number of nanoseconds is greater than 1 billion (the number of |
156 | /// nanoseconds in a second), then it will carry over into the seconds provided. | |
a7813a04 XL |
157 | /// |
158 | /// # Panics | |
159 | /// | |
160 | /// This constructor will panic if the carry from the nanoseconds overflows | |
161 | /// the seconds counter. | |
32a655c1 SL |
162 | /// |
163 | /// # Examples | |
164 | /// | |
165 | /// ``` | |
166 | /// use std::time::Duration; | |
167 | /// | |
168 | /// let five_seconds = Duration::new(5, 0); | |
169 | /// ``` | |
c1a9b12d | 170 | #[stable(feature = "duration", since = "1.3.0")] |
54a0048b | 171 | #[inline] |
3dfed10e XL |
172 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
173 | pub const fn new(secs: u64, nanos: u32) -> Duration { | |
174 | let secs = match secs.checked_add((nanos / NANOS_PER_SEC) as u64) { | |
175 | Some(secs) => secs, | |
176 | None => panic!("overflow in Duration::new"), | |
177 | }; | |
d9579d0f | 178 | let nanos = nanos % NANOS_PER_SEC; |
b7449926 | 179 | Duration { secs, nanos } |
1a4d82fc JJ |
180 | } |
181 | ||
3b2f2976 | 182 | /// Creates a new `Duration` from the specified number of whole seconds. |
32a655c1 SL |
183 | /// |
184 | /// # Examples | |
185 | /// | |
186 | /// ``` | |
187 | /// use std::time::Duration; | |
188 | /// | |
7cac9316 XL |
189 | /// let duration = Duration::from_secs(5); |
190 | /// | |
191 | /// assert_eq!(5, duration.as_secs()); | |
192 | /// assert_eq!(0, duration.subsec_nanos()); | |
32a655c1 | 193 | /// ``` |
c1a9b12d | 194 | #[stable(feature = "duration", since = "1.3.0")] |
54a0048b | 195 | #[inline] |
dfeec247 | 196 | #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] |
2c00a5a8 | 197 | pub const fn from_secs(secs: u64) -> Duration { |
b7449926 | 198 | Duration { secs, nanos: 0 } |
1a4d82fc JJ |
199 | } |
200 | ||
d9579d0f | 201 | /// Creates a new `Duration` from the specified number of milliseconds. |
32a655c1 SL |
202 | /// |
203 | /// # Examples | |
204 | /// | |
205 | /// ``` | |
206 | /// use std::time::Duration; | |
207 | /// | |
7cac9316 XL |
208 | /// let duration = Duration::from_millis(2569); |
209 | /// | |
210 | /// assert_eq!(2, duration.as_secs()); | |
ff7c6d11 | 211 | /// assert_eq!(569_000_000, duration.subsec_nanos()); |
32a655c1 | 212 | /// ``` |
c1a9b12d | 213 | #[stable(feature = "duration", since = "1.3.0")] |
54a0048b | 214 | #[inline] |
dfeec247 | 215 | #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] |
2c00a5a8 XL |
216 | pub const fn from_millis(millis: u64) -> Duration { |
217 | Duration { | |
218 | secs: millis / MILLIS_PER_SEC, | |
219 | nanos: ((millis % MILLIS_PER_SEC) as u32) * NANOS_PER_MILLI, | |
220 | } | |
1a4d82fc | 221 | } |
1a4d82fc | 222 | |
ea8adc8c XL |
223 | /// Creates a new `Duration` from the specified number of microseconds. |
224 | /// | |
225 | /// # Examples | |
226 | /// | |
227 | /// ``` | |
ea8adc8c XL |
228 | /// use std::time::Duration; |
229 | /// | |
230 | /// let duration = Duration::from_micros(1_000_002); | |
231 | /// | |
232 | /// assert_eq!(1, duration.as_secs()); | |
233 | /// assert_eq!(2000, duration.subsec_nanos()); | |
234 | /// ``` | |
83c7162d | 235 | #[stable(feature = "duration_from_micros", since = "1.27.0")] |
ea8adc8c | 236 | #[inline] |
dfeec247 | 237 | #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] |
2c00a5a8 XL |
238 | pub const fn from_micros(micros: u64) -> Duration { |
239 | Duration { | |
240 | secs: micros / MICROS_PER_SEC, | |
241 | nanos: ((micros % MICROS_PER_SEC) as u32) * NANOS_PER_MICRO, | |
242 | } | |
ea8adc8c XL |
243 | } |
244 | ||
ff7c6d11 XL |
245 | /// Creates a new `Duration` from the specified number of nanoseconds. |
246 | /// | |
247 | /// # Examples | |
248 | /// | |
249 | /// ``` | |
ff7c6d11 XL |
250 | /// use std::time::Duration; |
251 | /// | |
252 | /// let duration = Duration::from_nanos(1_000_000_123); | |
253 | /// | |
254 | /// assert_eq!(1, duration.as_secs()); | |
255 | /// assert_eq!(123, duration.subsec_nanos()); | |
256 | /// ``` | |
83c7162d | 257 | #[stable(feature = "duration_extras", since = "1.27.0")] |
ff7c6d11 | 258 | #[inline] |
dfeec247 | 259 | #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] |
2c00a5a8 XL |
260 | pub const fn from_nanos(nanos: u64) -> Duration { |
261 | Duration { | |
262 | secs: nanos / (NANOS_PER_SEC as u64), | |
263 | nanos: (nanos % (NANOS_PER_SEC as u64)) as u32, | |
264 | } | |
ff7c6d11 XL |
265 | } |
266 | ||
f035d41b XL |
267 | /// Returns true if this `Duration` spans no time. |
268 | /// | |
269 | /// # Examples | |
270 | /// | |
271 | /// ``` | |
272 | /// #![feature(duration_zero)] | |
273 | /// use std::time::Duration; | |
274 | /// | |
29967ef6 | 275 | /// assert!(Duration::ZERO.is_zero()); |
f035d41b XL |
276 | /// assert!(Duration::new(0, 0).is_zero()); |
277 | /// assert!(Duration::from_nanos(0).is_zero()); | |
278 | /// assert!(Duration::from_secs(0).is_zero()); | |
279 | /// | |
280 | /// assert!(!Duration::new(1, 1).is_zero()); | |
281 | /// assert!(!Duration::from_nanos(1).is_zero()); | |
282 | /// assert!(!Duration::from_secs(1).is_zero()); | |
283 | /// ``` | |
284 | #[unstable(feature = "duration_zero", issue = "73544")] | |
285 | #[inline] | |
286 | pub const fn is_zero(&self) -> bool { | |
287 | self.secs == 0 && self.nanos == 0 | |
288 | } | |
289 | ||
3b2f2976 | 290 | /// Returns the number of _whole_ seconds contained by this `Duration`. |
d9579d0f | 291 | /// |
3b2f2976 XL |
292 | /// The returned value does not include the fractional (nanosecond) part of the |
293 | /// duration, which can be obtained using [`subsec_nanos`]. | |
32a655c1 SL |
294 | /// |
295 | /// # Examples | |
296 | /// | |
297 | /// ``` | |
298 | /// use std::time::Duration; | |
299 | /// | |
7cac9316 XL |
300 | /// let duration = Duration::new(5, 730023852); |
301 | /// assert_eq!(duration.as_secs(), 5); | |
302 | /// ``` | |
303 | /// | |
304 | /// To determine the total number of seconds represented by the `Duration`, | |
305 | /// use `as_secs` in combination with [`subsec_nanos`]: | |
306 | /// | |
32a655c1 | 307 | /// ``` |
7cac9316 XL |
308 | /// use std::time::Duration; |
309 | /// | |
310 | /// let duration = Duration::new(5, 730023852); | |
311 | /// | |
312 | /// assert_eq!(5.730023852, | |
313 | /// duration.as_secs() as f64 | |
314 | /// + duration.subsec_nanos() as f64 * 1e-9); | |
315 | /// ``` | |
316 | /// | |
3dfed10e | 317 | /// [`subsec_nanos`]: Duration::subsec_nanos |
c1a9b12d | 318 | #[stable(feature = "duration", since = "1.3.0")] |
dfeec247 | 319 | #[rustc_const_stable(feature = "duration", since = "1.32.0")] |
54a0048b | 320 | #[inline] |
60c5eb7d XL |
321 | pub const fn as_secs(&self) -> u64 { |
322 | self.secs | |
323 | } | |
c1a9b12d | 324 | |
8faf50e0 | 325 | /// Returns the fractional part of this `Duration`, in whole milliseconds. |
ff7c6d11 XL |
326 | /// |
327 | /// This method does **not** return the length of the duration when | |
328 | /// represented by milliseconds. The returned number always represents a | |
0731742a | 329 | /// fractional portion of a second (i.e., it is less than one thousand). |
ff7c6d11 XL |
330 | /// |
331 | /// # Examples | |
332 | /// | |
333 | /// ``` | |
ff7c6d11 XL |
334 | /// use std::time::Duration; |
335 | /// | |
336 | /// let duration = Duration::from_millis(5432); | |
337 | /// assert_eq!(duration.as_secs(), 5); | |
2c00a5a8 | 338 | /// assert_eq!(duration.subsec_millis(), 432); |
ff7c6d11 | 339 | /// ``` |
83c7162d | 340 | #[stable(feature = "duration_extras", since = "1.27.0")] |
dfeec247 | 341 | #[rustc_const_stable(feature = "duration_extras", since = "1.32.0")] |
ff7c6d11 | 342 | #[inline] |
60c5eb7d XL |
343 | pub const fn subsec_millis(&self) -> u32 { |
344 | self.nanos / NANOS_PER_MILLI | |
345 | } | |
ff7c6d11 | 346 | |
8faf50e0 | 347 | /// Returns the fractional part of this `Duration`, in whole microseconds. |
ff7c6d11 XL |
348 | /// |
349 | /// This method does **not** return the length of the duration when | |
350 | /// represented by microseconds. The returned number always represents a | |
0731742a | 351 | /// fractional portion of a second (i.e., it is less than one million). |
ff7c6d11 XL |
352 | /// |
353 | /// # Examples | |
354 | /// | |
355 | /// ``` | |
ff7c6d11 XL |
356 | /// use std::time::Duration; |
357 | /// | |
358 | /// let duration = Duration::from_micros(1_234_567); | |
359 | /// assert_eq!(duration.as_secs(), 1); | |
2c00a5a8 | 360 | /// assert_eq!(duration.subsec_micros(), 234_567); |
ff7c6d11 | 361 | /// ``` |
83c7162d | 362 | #[stable(feature = "duration_extras", since = "1.27.0")] |
dfeec247 | 363 | #[rustc_const_stable(feature = "duration_extras", since = "1.32.0")] |
ff7c6d11 | 364 | #[inline] |
60c5eb7d XL |
365 | pub const fn subsec_micros(&self) -> u32 { |
366 | self.nanos / NANOS_PER_MICRO | |
367 | } | |
ff7c6d11 | 368 | |
3b2f2976 | 369 | /// Returns the fractional part of this `Duration`, in nanoseconds. |
c1a9b12d SL |
370 | /// |
371 | /// This method does **not** return the length of the duration when | |
372 | /// represented by nanoseconds. The returned number always represents a | |
0731742a | 373 | /// fractional portion of a second (i.e., it is less than one billion). |
32a655c1 SL |
374 | /// |
375 | /// # Examples | |
376 | /// | |
377 | /// ``` | |
378 | /// use std::time::Duration; | |
379 | /// | |
380 | /// let duration = Duration::from_millis(5010); | |
3b2f2976 XL |
381 | /// assert_eq!(duration.as_secs(), 5); |
382 | /// assert_eq!(duration.subsec_nanos(), 10_000_000); | |
32a655c1 | 383 | /// ``` |
c1a9b12d | 384 | #[stable(feature = "duration", since = "1.3.0")] |
dfeec247 | 385 | #[rustc_const_stable(feature = "duration", since = "1.32.0")] |
54a0048b | 386 | #[inline] |
60c5eb7d XL |
387 | pub const fn subsec_nanos(&self) -> u32 { |
388 | self.nanos | |
389 | } | |
94b46f34 | 390 | |
8faf50e0 | 391 | /// Returns the total number of whole milliseconds contained by this `Duration`. |
94b46f34 XL |
392 | /// |
393 | /// # Examples | |
394 | /// | |
395 | /// ``` | |
94b46f34 XL |
396 | /// use std::time::Duration; |
397 | /// | |
398 | /// let duration = Duration::new(5, 730023852); | |
399 | /// assert_eq!(duration.as_millis(), 5730); | |
400 | /// ``` | |
0731742a | 401 | #[stable(feature = "duration_as_u128", since = "1.33.0")] |
dfeec247 | 402 | #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] |
94b46f34 | 403 | #[inline] |
a1dfa0c6 | 404 | pub const fn as_millis(&self) -> u128 { |
94b46f34 XL |
405 | self.secs as u128 * MILLIS_PER_SEC as u128 + (self.nanos / NANOS_PER_MILLI) as u128 |
406 | } | |
407 | ||
8faf50e0 | 408 | /// Returns the total number of whole microseconds contained by this `Duration`. |
94b46f34 XL |
409 | /// |
410 | /// # Examples | |
411 | /// | |
412 | /// ``` | |
94b46f34 XL |
413 | /// use std::time::Duration; |
414 | /// | |
415 | /// let duration = Duration::new(5, 730023852); | |
416 | /// assert_eq!(duration.as_micros(), 5730023); | |
417 | /// ``` | |
0731742a | 418 | #[stable(feature = "duration_as_u128", since = "1.33.0")] |
dfeec247 | 419 | #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] |
94b46f34 | 420 | #[inline] |
a1dfa0c6 | 421 | pub const fn as_micros(&self) -> u128 { |
94b46f34 XL |
422 | self.secs as u128 * MICROS_PER_SEC as u128 + (self.nanos / NANOS_PER_MICRO) as u128 |
423 | } | |
424 | ||
425 | /// Returns the total number of nanoseconds contained by this `Duration`. | |
426 | /// | |
427 | /// # Examples | |
428 | /// | |
429 | /// ``` | |
94b46f34 XL |
430 | /// use std::time::Duration; |
431 | /// | |
432 | /// let duration = Duration::new(5, 730023852); | |
433 | /// assert_eq!(duration.as_nanos(), 5730023852); | |
434 | /// ``` | |
0731742a | 435 | #[stable(feature = "duration_as_u128", since = "1.33.0")] |
dfeec247 | 436 | #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] |
94b46f34 | 437 | #[inline] |
a1dfa0c6 | 438 | pub const fn as_nanos(&self) -> u128 { |
94b46f34 XL |
439 | self.secs as u128 * NANOS_PER_SEC as u128 + self.nanos as u128 |
440 | } | |
9e0c209e | 441 | |
32a655c1 | 442 | /// Checked `Duration` addition. Computes `self + other`, returning [`None`] |
9e0c209e SL |
443 | /// if overflow occurred. |
444 | /// | |
445 | /// # Examples | |
446 | /// | |
447 | /// Basic usage: | |
448 | /// | |
449 | /// ``` | |
9e0c209e SL |
450 | /// use std::time::Duration; |
451 | /// | |
452 | /// assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1))); | |
ba9703b0 | 453 | /// assert_eq!(Duration::new(1, 0).checked_add(Duration::new(u64::MAX, 0)), None); |
9e0c209e | 454 | /// ``` |
32a655c1 | 455 | #[stable(feature = "duration_checked_ops", since = "1.16.0")] |
9e0c209e | 456 | #[inline] |
3dfed10e XL |
457 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
458 | pub const fn checked_add(self, rhs: Duration) -> Option<Duration> { | |
9e0c209e SL |
459 | if let Some(mut secs) = self.secs.checked_add(rhs.secs) { |
460 | let mut nanos = self.nanos + rhs.nanos; | |
461 | if nanos >= NANOS_PER_SEC { | |
462 | nanos -= NANOS_PER_SEC; | |
463 | if let Some(new_secs) = secs.checked_add(1) { | |
464 | secs = new_secs; | |
465 | } else { | |
466 | return None; | |
467 | } | |
468 | } | |
469 | debug_assert!(nanos < NANOS_PER_SEC); | |
60c5eb7d | 470 | Some(Duration { secs, nanos }) |
9e0c209e SL |
471 | } else { |
472 | None | |
473 | } | |
474 | } | |
475 | ||
1b1a35ee XL |
476 | /// Saturating `Duration` addition. Computes `self + other`, returning [`Duration::MAX`] |
477 | /// if overflow occurred. | |
478 | /// | |
479 | /// # Examples | |
480 | /// | |
481 | /// ``` | |
482 | /// #![feature(duration_saturating_ops)] | |
483 | /// #![feature(duration_constants)] | |
484 | /// use std::time::Duration; | |
485 | /// | |
486 | /// assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1)); | |
487 | /// assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX); | |
488 | /// ``` | |
489 | #[unstable(feature = "duration_saturating_ops", issue = "76416")] | |
490 | #[inline] | |
491 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] | |
492 | pub const fn saturating_add(self, rhs: Duration) -> Duration { | |
493 | match self.checked_add(rhs) { | |
494 | Some(res) => res, | |
495 | None => Duration::MAX, | |
496 | } | |
497 | } | |
498 | ||
32a655c1 | 499 | /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`] |
ff7c6d11 | 500 | /// if the result would be negative or if overflow occurred. |
9e0c209e SL |
501 | /// |
502 | /// # Examples | |
503 | /// | |
504 | /// Basic usage: | |
505 | /// | |
506 | /// ``` | |
9e0c209e SL |
507 | /// use std::time::Duration; |
508 | /// | |
509 | /// assert_eq!(Duration::new(0, 1).checked_sub(Duration::new(0, 0)), Some(Duration::new(0, 1))); | |
510 | /// assert_eq!(Duration::new(0, 0).checked_sub(Duration::new(0, 1)), None); | |
511 | /// ``` | |
32a655c1 | 512 | #[stable(feature = "duration_checked_ops", since = "1.16.0")] |
9e0c209e | 513 | #[inline] |
3dfed10e XL |
514 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
515 | pub const fn checked_sub(self, rhs: Duration) -> Option<Duration> { | |
9e0c209e SL |
516 | if let Some(mut secs) = self.secs.checked_sub(rhs.secs) { |
517 | let nanos = if self.nanos >= rhs.nanos { | |
518 | self.nanos - rhs.nanos | |
519 | } else { | |
520 | if let Some(sub_secs) = secs.checked_sub(1) { | |
521 | secs = sub_secs; | |
522 | self.nanos + NANOS_PER_SEC - rhs.nanos | |
523 | } else { | |
524 | return None; | |
525 | } | |
526 | }; | |
527 | debug_assert!(nanos < NANOS_PER_SEC); | |
b7449926 | 528 | Some(Duration { secs, nanos }) |
9e0c209e SL |
529 | } else { |
530 | None | |
531 | } | |
532 | } | |
533 | ||
29967ef6 | 534 | /// Saturating `Duration` subtraction. Computes `self - other`, returning [`Duration::ZERO`] |
1b1a35ee XL |
535 | /// if the result would be negative or if overflow occurred. |
536 | /// | |
537 | /// # Examples | |
538 | /// | |
539 | /// ``` | |
540 | /// #![feature(duration_saturating_ops)] | |
29967ef6 | 541 | /// #![feature(duration_zero)] |
1b1a35ee XL |
542 | /// use std::time::Duration; |
543 | /// | |
544 | /// assert_eq!(Duration::new(0, 1).saturating_sub(Duration::new(0, 0)), Duration::new(0, 1)); | |
29967ef6 | 545 | /// assert_eq!(Duration::new(0, 0).saturating_sub(Duration::new(0, 1)), Duration::ZERO); |
1b1a35ee XL |
546 | /// ``` |
547 | #[unstable(feature = "duration_saturating_ops", issue = "76416")] | |
548 | #[inline] | |
549 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] | |
550 | pub const fn saturating_sub(self, rhs: Duration) -> Duration { | |
551 | match self.checked_sub(rhs) { | |
552 | Some(res) => res, | |
29967ef6 | 553 | None => Duration::ZERO, |
1b1a35ee XL |
554 | } |
555 | } | |
556 | ||
32a655c1 SL |
557 | /// Checked `Duration` multiplication. Computes `self * other`, returning |
558 | /// [`None`] if overflow occurred. | |
559 | /// | |
9e0c209e SL |
560 | /// # Examples |
561 | /// | |
562 | /// Basic usage: | |
563 | /// | |
564 | /// ``` | |
9e0c209e SL |
565 | /// use std::time::Duration; |
566 | /// | |
567 | /// assert_eq!(Duration::new(0, 500_000_001).checked_mul(2), Some(Duration::new(1, 2))); | |
ba9703b0 | 568 | /// assert_eq!(Duration::new(u64::MAX - 1, 0).checked_mul(2), None); |
9e0c209e | 569 | /// ``` |
32a655c1 | 570 | #[stable(feature = "duration_checked_ops", since = "1.16.0")] |
9e0c209e | 571 | #[inline] |
3dfed10e XL |
572 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
573 | pub const fn checked_mul(self, rhs: u32) -> Option<Duration> { | |
9e0c209e SL |
574 | // Multiply nanoseconds as u64, because it cannot overflow that way. |
575 | let total_nanos = self.nanos as u64 * rhs as u64; | |
576 | let extra_secs = total_nanos / (NANOS_PER_SEC as u64); | |
577 | let nanos = (total_nanos % (NANOS_PER_SEC as u64)) as u32; | |
3dfed10e XL |
578 | if let Some(s) = self.secs.checked_mul(rhs as u64) { |
579 | if let Some(secs) = s.checked_add(extra_secs) { | |
580 | debug_assert!(nanos < NANOS_PER_SEC); | |
581 | return Some(Duration { secs, nanos }); | |
582 | } | |
9e0c209e | 583 | } |
3dfed10e | 584 | None |
9e0c209e SL |
585 | } |
586 | ||
1b1a35ee XL |
587 | /// Saturating `Duration` multiplication. Computes `self * other`, returning |
588 | /// [`Duration::MAX`] if overflow occurred. | |
589 | /// | |
590 | /// # Examples | |
591 | /// | |
592 | /// ``` | |
593 | /// #![feature(duration_saturating_ops)] | |
594 | /// #![feature(duration_constants)] | |
595 | /// use std::time::Duration; | |
596 | /// | |
597 | /// assert_eq!(Duration::new(0, 500_000_001).saturating_mul(2), Duration::new(1, 2)); | |
598 | /// assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX); | |
599 | /// ``` | |
600 | #[unstable(feature = "duration_saturating_ops", issue = "76416")] | |
601 | #[inline] | |
602 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] | |
603 | pub const fn saturating_mul(self, rhs: u32) -> Duration { | |
604 | match self.checked_mul(rhs) { | |
605 | Some(res) => res, | |
606 | None => Duration::MAX, | |
607 | } | |
608 | } | |
609 | ||
32a655c1 SL |
610 | /// Checked `Duration` division. Computes `self / other`, returning [`None`] |
611 | /// if `other == 0`. | |
612 | /// | |
9e0c209e SL |
613 | /// # Examples |
614 | /// | |
615 | /// Basic usage: | |
616 | /// | |
617 | /// ``` | |
9e0c209e SL |
618 | /// use std::time::Duration; |
619 | /// | |
620 | /// assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0))); | |
621 | /// assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000))); | |
622 | /// assert_eq!(Duration::new(2, 0).checked_div(0), None); | |
623 | /// ``` | |
32a655c1 | 624 | #[stable(feature = "duration_checked_ops", since = "1.16.0")] |
9e0c209e | 625 | #[inline] |
3dfed10e XL |
626 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
627 | pub const fn checked_div(self, rhs: u32) -> Option<Duration> { | |
9e0c209e SL |
628 | if rhs != 0 { |
629 | let secs = self.secs / (rhs as u64); | |
630 | let carry = self.secs - secs * (rhs as u64); | |
631 | let extra_nanos = carry * (NANOS_PER_SEC as u64) / (rhs as u64); | |
632 | let nanos = self.nanos / rhs + (extra_nanos as u32); | |
633 | debug_assert!(nanos < NANOS_PER_SEC); | |
b7449926 | 634 | Some(Duration { secs, nanos }) |
9e0c209e SL |
635 | } else { |
636 | None | |
637 | } | |
638 | } | |
0bf4aa26 XL |
639 | |
640 | /// Returns the number of seconds contained by this `Duration` as `f64`. | |
641 | /// | |
642 | /// The returned value does include the fractional (nanosecond) part of the duration. | |
643 | /// | |
644 | /// # Examples | |
645 | /// ``` | |
0bf4aa26 XL |
646 | /// use std::time::Duration; |
647 | /// | |
648 | /// let dur = Duration::new(2, 700_000_000); | |
532ac7d7 | 649 | /// assert_eq!(dur.as_secs_f64(), 2.7); |
0bf4aa26 | 650 | /// ``` |
416331ca | 651 | #[stable(feature = "duration_float", since = "1.38.0")] |
0bf4aa26 | 652 | #[inline] |
3dfed10e XL |
653 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
654 | pub const fn as_secs_f64(&self) -> f64 { | |
0bf4aa26 XL |
655 | (self.secs as f64) + (self.nanos as f64) / (NANOS_PER_SEC as f64) |
656 | } | |
657 | ||
532ac7d7 XL |
658 | /// Returns the number of seconds contained by this `Duration` as `f32`. |
659 | /// | |
660 | /// The returned value does include the fractional (nanosecond) part of the duration. | |
661 | /// | |
662 | /// # Examples | |
663 | /// ``` | |
532ac7d7 XL |
664 | /// use std::time::Duration; |
665 | /// | |
666 | /// let dur = Duration::new(2, 700_000_000); | |
667 | /// assert_eq!(dur.as_secs_f32(), 2.7); | |
668 | /// ``` | |
416331ca | 669 | #[stable(feature = "duration_float", since = "1.38.0")] |
532ac7d7 | 670 | #[inline] |
3dfed10e XL |
671 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
672 | pub const fn as_secs_f32(&self) -> f32 { | |
532ac7d7 XL |
673 | (self.secs as f32) + (self.nanos as f32) / (NANOS_PER_SEC as f32) |
674 | } | |
675 | ||
676 | /// Creates a new `Duration` from the specified number of seconds represented | |
677 | /// as `f64`. | |
0bf4aa26 XL |
678 | /// |
679 | /// # Panics | |
680 | /// This constructor will panic if `secs` is not finite, negative or overflows `Duration`. | |
681 | /// | |
682 | /// # Examples | |
683 | /// ``` | |
0bf4aa26 XL |
684 | /// use std::time::Duration; |
685 | /// | |
532ac7d7 | 686 | /// let dur = Duration::from_secs_f64(2.7); |
0bf4aa26 XL |
687 | /// assert_eq!(dur, Duration::new(2, 700_000_000)); |
688 | /// ``` | |
416331ca | 689 | #[stable(feature = "duration_float", since = "1.38.0")] |
0bf4aa26 | 690 | #[inline] |
1b1a35ee XL |
691 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
692 | pub const fn from_secs_f64(secs: f64) -> Duration { | |
60c5eb7d XL |
693 | const MAX_NANOS_F64: f64 = ((u64::MAX as u128 + 1) * (NANOS_PER_SEC as u128)) as f64; |
694 | let nanos = secs * (NANOS_PER_SEC as f64); | |
0bf4aa26 XL |
695 | if !nanos.is_finite() { |
696 | panic!("got non-finite value when converting float to duration"); | |
697 | } | |
698 | if nanos >= MAX_NANOS_F64 { | |
699 | panic!("overflow when converting float to duration"); | |
700 | } | |
701 | if nanos < 0.0 { | |
702 | panic!("underflow when converting float to duration"); | |
703 | } | |
60c5eb7d | 704 | let nanos = nanos as u128; |
0bf4aa26 XL |
705 | Duration { |
706 | secs: (nanos / (NANOS_PER_SEC as u128)) as u64, | |
707 | nanos: (nanos % (NANOS_PER_SEC as u128)) as u32, | |
708 | } | |
709 | } | |
710 | ||
532ac7d7 XL |
711 | /// Creates a new `Duration` from the specified number of seconds represented |
712 | /// as `f32`. | |
713 | /// | |
714 | /// # Panics | |
715 | /// This constructor will panic if `secs` is not finite, negative or overflows `Duration`. | |
716 | /// | |
717 | /// # Examples | |
718 | /// ``` | |
532ac7d7 XL |
719 | /// use std::time::Duration; |
720 | /// | |
721 | /// let dur = Duration::from_secs_f32(2.7); | |
722 | /// assert_eq!(dur, Duration::new(2, 700_000_000)); | |
723 | /// ``` | |
416331ca | 724 | #[stable(feature = "duration_float", since = "1.38.0")] |
532ac7d7 | 725 | #[inline] |
1b1a35ee XL |
726 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
727 | pub const fn from_secs_f32(secs: f32) -> Duration { | |
60c5eb7d XL |
728 | const MAX_NANOS_F32: f32 = ((u64::MAX as u128 + 1) * (NANOS_PER_SEC as u128)) as f32; |
729 | let nanos = secs * (NANOS_PER_SEC as f32); | |
532ac7d7 XL |
730 | if !nanos.is_finite() { |
731 | panic!("got non-finite value when converting float to duration"); | |
732 | } | |
733 | if nanos >= MAX_NANOS_F32 { | |
734 | panic!("overflow when converting float to duration"); | |
735 | } | |
736 | if nanos < 0.0 { | |
737 | panic!("underflow when converting float to duration"); | |
738 | } | |
60c5eb7d | 739 | let nanos = nanos as u128; |
532ac7d7 XL |
740 | Duration { |
741 | secs: (nanos / (NANOS_PER_SEC as u128)) as u64, | |
742 | nanos: (nanos % (NANOS_PER_SEC as u128)) as u32, | |
743 | } | |
744 | } | |
745 | ||
9fa01778 | 746 | /// Multiplies `Duration` by `f64`. |
0bf4aa26 XL |
747 | /// |
748 | /// # Panics | |
749 | /// This method will panic if result is not finite, negative or overflows `Duration`. | |
750 | /// | |
751 | /// # Examples | |
752 | /// ``` | |
0bf4aa26 XL |
753 | /// use std::time::Duration; |
754 | /// | |
755 | /// let dur = Duration::new(2, 700_000_000); | |
756 | /// assert_eq!(dur.mul_f64(3.14), Duration::new(8, 478_000_000)); | |
757 | /// assert_eq!(dur.mul_f64(3.14e5), Duration::new(847_800, 0)); | |
758 | /// ``` | |
416331ca | 759 | #[stable(feature = "duration_float", since = "1.38.0")] |
0bf4aa26 | 760 | #[inline] |
1b1a35ee XL |
761 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
762 | pub const fn mul_f64(self, rhs: f64) -> Duration { | |
532ac7d7 XL |
763 | Duration::from_secs_f64(rhs * self.as_secs_f64()) |
764 | } | |
765 | ||
766 | /// Multiplies `Duration` by `f32`. | |
767 | /// | |
768 | /// # Panics | |
769 | /// This method will panic if result is not finite, negative or overflows `Duration`. | |
770 | /// | |
771 | /// # Examples | |
772 | /// ``` | |
532ac7d7 XL |
773 | /// use std::time::Duration; |
774 | /// | |
775 | /// let dur = Duration::new(2, 700_000_000); | |
776 | /// // note that due to rounding errors result is slightly different | |
777 | /// // from 8.478 and 847800.0 | |
778 | /// assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_640)); | |
779 | /// assert_eq!(dur.mul_f32(3.14e5), Duration::new(847799, 969_120_256)); | |
780 | /// ``` | |
416331ca | 781 | #[stable(feature = "duration_float", since = "1.38.0")] |
532ac7d7 | 782 | #[inline] |
1b1a35ee XL |
783 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
784 | pub const fn mul_f32(self, rhs: f32) -> Duration { | |
532ac7d7 | 785 | Duration::from_secs_f32(rhs * self.as_secs_f32()) |
0bf4aa26 XL |
786 | } |
787 | ||
788 | /// Divide `Duration` by `f64`. | |
789 | /// | |
790 | /// # Panics | |
791 | /// This method will panic if result is not finite, negative or overflows `Duration`. | |
792 | /// | |
793 | /// # Examples | |
794 | /// ``` | |
0bf4aa26 XL |
795 | /// use std::time::Duration; |
796 | /// | |
797 | /// let dur = Duration::new(2, 700_000_000); | |
798 | /// assert_eq!(dur.div_f64(3.14), Duration::new(0, 859_872_611)); | |
799 | /// // note that truncation is used, not rounding | |
800 | /// assert_eq!(dur.div_f64(3.14e5), Duration::new(0, 8_598)); | |
801 | /// ``` | |
416331ca | 802 | #[stable(feature = "duration_float", since = "1.38.0")] |
0bf4aa26 | 803 | #[inline] |
1b1a35ee XL |
804 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
805 | pub const fn div_f64(self, rhs: f64) -> Duration { | |
532ac7d7 XL |
806 | Duration::from_secs_f64(self.as_secs_f64() / rhs) |
807 | } | |
808 | ||
809 | /// Divide `Duration` by `f32`. | |
810 | /// | |
811 | /// # Panics | |
812 | /// This method will panic if result is not finite, negative or overflows `Duration`. | |
813 | /// | |
814 | /// # Examples | |
815 | /// ``` | |
532ac7d7 XL |
816 | /// use std::time::Duration; |
817 | /// | |
818 | /// let dur = Duration::new(2, 700_000_000); | |
819 | /// // note that due to rounding errors result is slightly | |
820 | /// // different from 0.859_872_611 | |
821 | /// assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_576)); | |
822 | /// // note that truncation is used, not rounding | |
823 | /// assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_598)); | |
824 | /// ``` | |
416331ca | 825 | #[stable(feature = "duration_float", since = "1.38.0")] |
532ac7d7 | 826 | #[inline] |
1b1a35ee XL |
827 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
828 | pub const fn div_f32(self, rhs: f32) -> Duration { | |
532ac7d7 | 829 | Duration::from_secs_f32(self.as_secs_f32() / rhs) |
0bf4aa26 XL |
830 | } |
831 | ||
832 | /// Divide `Duration` by `Duration` and return `f64`. | |
833 | /// | |
834 | /// # Examples | |
835 | /// ``` | |
416331ca | 836 | /// #![feature(div_duration)] |
0bf4aa26 XL |
837 | /// use std::time::Duration; |
838 | /// | |
839 | /// let dur1 = Duration::new(2, 700_000_000); | |
840 | /// let dur2 = Duration::new(5, 400_000_000); | |
532ac7d7 XL |
841 | /// assert_eq!(dur1.div_duration_f64(dur2), 0.5); |
842 | /// ``` | |
416331ca | 843 | #[unstable(feature = "div_duration", issue = "63139")] |
532ac7d7 | 844 | #[inline] |
3dfed10e XL |
845 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
846 | pub const fn div_duration_f64(self, rhs: Duration) -> f64 { | |
532ac7d7 XL |
847 | self.as_secs_f64() / rhs.as_secs_f64() |
848 | } | |
849 | ||
850 | /// Divide `Duration` by `Duration` and return `f32`. | |
851 | /// | |
852 | /// # Examples | |
853 | /// ``` | |
416331ca | 854 | /// #![feature(div_duration)] |
532ac7d7 XL |
855 | /// use std::time::Duration; |
856 | /// | |
857 | /// let dur1 = Duration::new(2, 700_000_000); | |
858 | /// let dur2 = Duration::new(5, 400_000_000); | |
859 | /// assert_eq!(dur1.div_duration_f32(dur2), 0.5); | |
0bf4aa26 | 860 | /// ``` |
416331ca | 861 | #[unstable(feature = "div_duration", issue = "63139")] |
0bf4aa26 | 862 | #[inline] |
3dfed10e XL |
863 | #[rustc_const_unstable(feature = "duration_consts_2", issue = "72440")] |
864 | pub const fn div_duration_f32(self, rhs: Duration) -> f32 { | |
532ac7d7 | 865 | self.as_secs_f32() / rhs.as_secs_f32() |
0bf4aa26 | 866 | } |
1a4d82fc JJ |
867 | } |
868 | ||
92a42be0 | 869 | #[stable(feature = "duration", since = "1.3.0")] |
1a4d82fc JJ |
870 | impl Add for Duration { |
871 | type Output = Duration; | |
872 | ||
873 | fn add(self, rhs: Duration) -> Duration { | |
9e0c209e | 874 | self.checked_add(rhs).expect("overflow when adding durations") |
1a4d82fc JJ |
875 | } |
876 | } | |
877 | ||
54a0048b SL |
878 | #[stable(feature = "time_augmented_assignment", since = "1.9.0")] |
879 | impl AddAssign for Duration { | |
880 | fn add_assign(&mut self, rhs: Duration) { | |
881 | *self = *self + rhs; | |
882 | } | |
883 | } | |
884 | ||
92a42be0 | 885 | #[stable(feature = "duration", since = "1.3.0")] |
1a4d82fc JJ |
886 | impl Sub for Duration { |
887 | type Output = Duration; | |
888 | ||
889 | fn sub(self, rhs: Duration) -> Duration { | |
9e0c209e | 890 | self.checked_sub(rhs).expect("overflow when subtracting durations") |
1a4d82fc JJ |
891 | } |
892 | } | |
893 | ||
54a0048b SL |
894 | #[stable(feature = "time_augmented_assignment", since = "1.9.0")] |
895 | impl SubAssign for Duration { | |
896 | fn sub_assign(&mut self, rhs: Duration) { | |
897 | *self = *self - rhs; | |
898 | } | |
899 | } | |
900 | ||
92a42be0 | 901 | #[stable(feature = "duration", since = "1.3.0")] |
d9579d0f | 902 | impl Mul<u32> for Duration { |
1a4d82fc JJ |
903 | type Output = Duration; |
904 | ||
d9579d0f | 905 | fn mul(self, rhs: u32) -> Duration { |
9e0c209e | 906 | self.checked_mul(rhs).expect("overflow when multiplying duration by scalar") |
1a4d82fc | 907 | } |
0bf4aa26 XL |
908 | } |
909 | ||
910 | #[stable(feature = "symmetric_u32_duration_mul", since = "1.31.0")] | |
911 | impl Mul<Duration> for u32 { | |
912 | type Output = Duration; | |
913 | ||
914 | fn mul(self, rhs: Duration) -> Duration { | |
915 | rhs * self | |
916 | } | |
1a4d82fc JJ |
917 | } |
918 | ||
54a0048b SL |
919 | #[stable(feature = "time_augmented_assignment", since = "1.9.0")] |
920 | impl MulAssign<u32> for Duration { | |
921 | fn mul_assign(&mut self, rhs: u32) { | |
922 | *self = *self * rhs; | |
923 | } | |
924 | } | |
925 | ||
92a42be0 | 926 | #[stable(feature = "duration", since = "1.3.0")] |
d9579d0f | 927 | impl Div<u32> for Duration { |
1a4d82fc JJ |
928 | type Output = Duration; |
929 | ||
d9579d0f | 930 | fn div(self, rhs: u32) -> Duration { |
9e0c209e | 931 | self.checked_div(rhs).expect("divide by zero error when dividing duration by scalar") |
1a4d82fc JJ |
932 | } |
933 | } | |
934 | ||
54a0048b SL |
935 | #[stable(feature = "time_augmented_assignment", since = "1.9.0")] |
936 | impl DivAssign<u32> for Duration { | |
937 | fn div_assign(&mut self, rhs: u32) { | |
938 | *self = *self / rhs; | |
939 | } | |
940 | } | |
941 | ||
8faf50e0 XL |
942 | macro_rules! sum_durations { |
943 | ($iter:expr) => {{ | |
944 | let mut total_secs: u64 = 0; | |
945 | let mut total_nanos: u64 = 0; | |
946 | ||
947 | for entry in $iter { | |
60c5eb7d XL |
948 | total_secs = |
949 | total_secs.checked_add(entry.secs).expect("overflow in iter::sum over durations"); | |
8faf50e0 XL |
950 | total_nanos = match total_nanos.checked_add(entry.nanos as u64) { |
951 | Some(n) => n, | |
952 | None => { | |
953 | total_secs = total_secs | |
954 | .checked_add(total_nanos / NANOS_PER_SEC as u64) | |
955 | .expect("overflow in iter::sum over durations"); | |
956 | (total_nanos % NANOS_PER_SEC as u64) + entry.nanos as u64 | |
957 | } | |
958 | }; | |
959 | } | |
960 | total_secs = total_secs | |
961 | .checked_add(total_nanos / NANOS_PER_SEC as u64) | |
962 | .expect("overflow in iter::sum over durations"); | |
963 | total_nanos = total_nanos % NANOS_PER_SEC as u64; | |
60c5eb7d | 964 | Duration { secs: total_secs, nanos: total_nanos as u32 } |
8faf50e0 XL |
965 | }}; |
966 | } | |
967 | ||
32a655c1 SL |
968 | #[stable(feature = "duration_sum", since = "1.16.0")] |
969 | impl Sum for Duration { | |
60c5eb7d | 970 | fn sum<I: Iterator<Item = Duration>>(iter: I) -> Duration { |
8faf50e0 | 971 | sum_durations!(iter) |
32a655c1 SL |
972 | } |
973 | } | |
974 | ||
975 | #[stable(feature = "duration_sum", since = "1.16.0")] | |
976 | impl<'a> Sum<&'a Duration> for Duration { | |
60c5eb7d | 977 | fn sum<I: Iterator<Item = &'a Duration>>(iter: I) -> Duration { |
8faf50e0 | 978 | sum_durations!(iter) |
32a655c1 SL |
979 | } |
980 | } | |
94b46f34 XL |
981 | |
982 | #[stable(feature = "duration_debug_impl", since = "1.27.0")] | |
983 | impl fmt::Debug for Duration { | |
48663c56 | 984 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
94b46f34 XL |
985 | /// Formats a floating point number in decimal notation. |
986 | /// | |
987 | /// The number is given as the `integer_part` and a fractional part. | |
988 | /// The value of the fractional part is `fractional_part / divisor`. So | |
989 | /// `integer_part` = 3, `fractional_part` = 12 and `divisor` = 100 | |
990 | /// represents the number `3.012`. Trailing zeros are omitted. | |
991 | /// | |
992 | /// `divisor` must not be above 100_000_000. It also should be a power | |
993 | /// of 10, everything else doesn't make sense. `fractional_part` has | |
994 | /// to be less than `10 * divisor`! | |
995 | fn fmt_decimal( | |
48663c56 | 996 | f: &mut fmt::Formatter<'_>, |
94b46f34 XL |
997 | mut integer_part: u64, |
998 | mut fractional_part: u32, | |
999 | mut divisor: u32, | |
1000 | ) -> fmt::Result { | |
1001 | // Encode the fractional part into a temporary buffer. The buffer | |
1002 | // only need to hold 9 elements, because `fractional_part` has to | |
1003 | // be smaller than 10^9. The buffer is prefilled with '0' digits | |
1004 | // to simplify the code below. | |
1005 | let mut buf = [b'0'; 9]; | |
1006 | ||
1007 | // The next digit is written at this position | |
1008 | let mut pos = 0; | |
1009 | ||
1010 | // We keep writing digits into the buffer while there are non-zero | |
1011 | // digits left and we haven't written enough digits yet. | |
1012 | while fractional_part > 0 && pos < f.precision().unwrap_or(9) { | |
1013 | // Write new digit into the buffer | |
1014 | buf[pos] = b'0' + (fractional_part / divisor) as u8; | |
1015 | ||
1016 | fractional_part %= divisor; | |
1017 | divisor /= 10; | |
1018 | pos += 1; | |
1019 | } | |
1020 | ||
1021 | // If a precision < 9 was specified, there may be some non-zero | |
1022 | // digits left that weren't written into the buffer. In that case we | |
1023 | // need to perform rounding to match the semantics of printing | |
1024 | // normal floating point numbers. However, we only need to do work | |
1025 | // when rounding up. This happens if the first digit of the | |
1026 | // remaining ones is >= 5. | |
1027 | if fractional_part > 0 && fractional_part >= divisor * 5 { | |
1028 | // Round up the number contained in the buffer. We go through | |
1029 | // the buffer backwards and keep track of the carry. | |
1030 | let mut rev_pos = pos; | |
1031 | let mut carry = true; | |
1032 | while carry && rev_pos > 0 { | |
1033 | rev_pos -= 1; | |
1034 | ||
1035 | // If the digit in the buffer is not '9', we just need to | |
1036 | // increment it and can stop then (since we don't have a | |
1037 | // carry anymore). Otherwise, we set it to '0' (overflow) | |
1038 | // and continue. | |
1039 | if buf[rev_pos] < b'9' { | |
1040 | buf[rev_pos] += 1; | |
1041 | carry = false; | |
1042 | } else { | |
1043 | buf[rev_pos] = b'0'; | |
1044 | } | |
1045 | } | |
1046 | ||
1047 | // If we still have the carry bit set, that means that we set | |
1048 | // the whole buffer to '0's and need to increment the integer | |
1049 | // part. | |
1050 | if carry { | |
1051 | integer_part += 1; | |
1052 | } | |
1053 | } | |
1054 | ||
1055 | // Determine the end of the buffer: if precision is set, we just | |
1056 | // use as many digits from the buffer (capped to 9). If it isn't | |
1057 | // set, we only use all digits up to the last non-zero one. | |
48663c56 | 1058 | let end = f.precision().map(|p| crate::cmp::min(p, 9)).unwrap_or(pos); |
94b46f34 XL |
1059 | |
1060 | // If we haven't emitted a single fractional digit and the precision | |
1061 | // wasn't set to a non-zero value, we don't print the decimal point. | |
1062 | if end == 0 { | |
1063 | write!(f, "{}", integer_part) | |
1064 | } else { | |
60c5eb7d | 1065 | // SAFETY: We are only writing ASCII digits into the buffer and it was |
94b46f34 | 1066 | // initialized with '0's, so it contains valid UTF8. |
60c5eb7d | 1067 | let s = unsafe { crate::str::from_utf8_unchecked(&buf[..end]) }; |
94b46f34 XL |
1068 | |
1069 | // If the user request a precision > 9, we pad '0's at the end. | |
1070 | let w = f.precision().unwrap_or(pos); | |
1071 | write!(f, "{}.{:0<width$}", integer_part, s, width = w) | |
1072 | } | |
1073 | } | |
1074 | ||
1075 | // Print leading '+' sign if requested | |
1076 | if f.sign_plus() { | |
1077 | write!(f, "+")?; | |
1078 | } | |
1079 | ||
1080 | if self.secs > 0 { | |
5869c6ff | 1081 | fmt_decimal(f, self.secs, self.nanos, NANOS_PER_SEC / 10)?; |
94b46f34 | 1082 | f.write_str("s") |
5869c6ff XL |
1083 | } else if self.nanos >= NANOS_PER_MILLI { |
1084 | fmt_decimal( | |
1085 | f, | |
1086 | (self.nanos / NANOS_PER_MILLI) as u64, | |
1087 | self.nanos % NANOS_PER_MILLI, | |
1088 | NANOS_PER_MILLI / 10, | |
1089 | )?; | |
94b46f34 | 1090 | f.write_str("ms") |
5869c6ff XL |
1091 | } else if self.nanos >= NANOS_PER_MICRO { |
1092 | fmt_decimal( | |
1093 | f, | |
1094 | (self.nanos / NANOS_PER_MICRO) as u64, | |
1095 | self.nanos % NANOS_PER_MICRO, | |
1096 | NANOS_PER_MICRO / 10, | |
1097 | )?; | |
94b46f34 XL |
1098 | f.write_str("µs") |
1099 | } else { | |
1100 | fmt_decimal(f, self.nanos as u64, 0, 1)?; | |
1101 | f.write_str("ns") | |
1102 | } | |
1103 | } | |
1104 | } |