1 | #![stable (feature = "duration_core" , since = "1.25.0" )] |
2 | |
3 | //! Temporal quantification. |
4 | //! |
5 | //! # Examples: |
6 | //! |
7 | //! There are multiple ways to create a new [`Duration`]: |
8 | //! |
9 | //! ``` |
10 | //! # use std::time::Duration; |
11 | //! let five_seconds = Duration::from_secs(5); |
12 | //! assert_eq!(five_seconds, Duration::from_millis(5_000)); |
13 | //! assert_eq!(five_seconds, Duration::from_micros(5_000_000)); |
14 | //! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000)); |
15 | //! |
16 | //! let ten_seconds = Duration::from_secs(10); |
17 | //! let seven_nanos = Duration::from_nanos(7); |
18 | //! let total = ten_seconds + seven_nanos; |
19 | //! assert_eq!(total, Duration::new(10, 7)); |
20 | //! ``` |
21 | |
22 | use crate::fmt; |
23 | use crate::iter::Sum; |
24 | use crate::num::niche_types::Nanoseconds; |
25 | use crate::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign}; |
26 | |
27 | const NANOS_PER_SEC: u32 = 1_000_000_000; |
28 | const NANOS_PER_MILLI: u32 = 1_000_000; |
29 | const NANOS_PER_MICRO: u32 = 1_000; |
30 | const MILLIS_PER_SEC: u64 = 1_000; |
31 | const MICROS_PER_SEC: u64 = 1_000_000; |
32 | #[unstable (feature = "duration_units" , issue = "120301" )] |
33 | const SECS_PER_MINUTE: u64 = 60; |
34 | #[unstable (feature = "duration_units" , issue = "120301" )] |
35 | const MINS_PER_HOUR: u64 = 60; |
36 | #[unstable (feature = "duration_units" , issue = "120301" )] |
37 | const HOURS_PER_DAY: u64 = 24; |
38 | #[unstable (feature = "duration_units" , issue = "120301" )] |
39 | const DAYS_PER_WEEK: u64 = 7; |
40 | |
41 | /// A `Duration` type to represent a span of time, typically used for system |
42 | /// timeouts. |
43 | /// |
44 | /// Each `Duration` is composed of a whole number of seconds and a fractional part |
45 | /// represented in nanoseconds. If the underlying system does not support |
46 | /// nanosecond-level precision, APIs binding a system timeout will typically round up |
47 | /// the number of nanoseconds. |
48 | /// |
49 | /// [`Duration`]s implement many common traits, including [`Add`], [`Sub`], and other |
50 | /// [`ops`] traits. It implements [`Default`] by returning a zero-length `Duration`. |
51 | /// |
52 | /// [`ops`]: crate::ops |
53 | /// |
54 | /// # Examples |
55 | /// |
56 | /// ``` |
57 | /// use std::time::Duration; |
58 | /// |
59 | /// let five_seconds = Duration::new(5, 0); |
60 | /// let five_seconds_and_five_nanos = five_seconds + Duration::new(0, 5); |
61 | /// |
62 | /// assert_eq!(five_seconds_and_five_nanos.as_secs(), 5); |
63 | /// assert_eq!(five_seconds_and_five_nanos.subsec_nanos(), 5); |
64 | /// |
65 | /// let ten_millis = Duration::from_millis(10); |
66 | /// ``` |
67 | /// |
68 | /// # Formatting `Duration` values |
69 | /// |
70 | /// `Duration` intentionally does not have a `Display` impl, as there are a |
71 | /// variety of ways to format spans of time for human readability. `Duration` |
72 | /// provides a `Debug` impl that shows the full precision of the value. |
73 | /// |
74 | /// The `Debug` output uses the non-ASCII "µs" suffix for microseconds. If your |
75 | /// program output may appear in contexts that cannot rely on full Unicode |
76 | /// compatibility, you may wish to format `Duration` objects yourself or use a |
77 | /// crate to do so. |
78 | #[stable (feature = "duration" , since = "1.3.0" )] |
79 | #[derive (Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] |
80 | #[rustc_diagnostic_item = "Duration" ] |
81 | pub struct Duration { |
82 | secs: u64, |
83 | nanos: Nanoseconds, // Always 0 <= nanos < NANOS_PER_SEC |
84 | } |
85 | |
86 | impl Duration { |
87 | /// The duration of one second. |
88 | /// |
89 | /// # Examples |
90 | /// |
91 | /// ``` |
92 | /// #![feature(duration_constants)] |
93 | /// use std::time::Duration; |
94 | /// |
95 | /// assert_eq!(Duration::SECOND, Duration::from_secs(1)); |
96 | /// ``` |
97 | #[unstable (feature = "duration_constants" , issue = "57391" )] |
98 | pub const SECOND: Duration = Duration::from_secs(1); |
99 | |
100 | /// The duration of one millisecond. |
101 | /// |
102 | /// # Examples |
103 | /// |
104 | /// ``` |
105 | /// #![feature(duration_constants)] |
106 | /// use std::time::Duration; |
107 | /// |
108 | /// assert_eq!(Duration::MILLISECOND, Duration::from_millis(1)); |
109 | /// ``` |
110 | #[unstable (feature = "duration_constants" , issue = "57391" )] |
111 | pub const MILLISECOND: Duration = Duration::from_millis(1); |
112 | |
113 | /// The duration of one microsecond. |
114 | /// |
115 | /// # Examples |
116 | /// |
117 | /// ``` |
118 | /// #![feature(duration_constants)] |
119 | /// use std::time::Duration; |
120 | /// |
121 | /// assert_eq!(Duration::MICROSECOND, Duration::from_micros(1)); |
122 | /// ``` |
123 | #[unstable (feature = "duration_constants" , issue = "57391" )] |
124 | pub const MICROSECOND: Duration = Duration::from_micros(1); |
125 | |
126 | /// The duration of one nanosecond. |
127 | /// |
128 | /// # Examples |
129 | /// |
130 | /// ``` |
131 | /// #![feature(duration_constants)] |
132 | /// use std::time::Duration; |
133 | /// |
134 | /// assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1)); |
135 | /// ``` |
136 | #[unstable (feature = "duration_constants" , issue = "57391" )] |
137 | pub const NANOSECOND: Duration = Duration::from_nanos(1); |
138 | |
139 | /// A duration of zero time. |
140 | /// |
141 | /// # Examples |
142 | /// |
143 | /// ``` |
144 | /// use std::time::Duration; |
145 | /// |
146 | /// let duration = Duration::ZERO; |
147 | /// assert!(duration.is_zero()); |
148 | /// assert_eq!(duration.as_nanos(), 0); |
149 | /// ``` |
150 | #[stable (feature = "duration_zero" , since = "1.53.0" )] |
151 | pub const ZERO: Duration = Duration::from_nanos(0); |
152 | |
153 | /// The maximum duration. |
154 | /// |
155 | /// May vary by platform as necessary. Must be able to contain the difference between |
156 | /// two instances of [`Instant`] or two instances of [`SystemTime`]. |
157 | /// This constraint gives it a value of about 584,942,417,355 years in practice, |
158 | /// which is currently used on all platforms. |
159 | /// |
160 | /// # Examples |
161 | /// |
162 | /// ``` |
163 | /// use std::time::Duration; |
164 | /// |
165 | /// assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1)); |
166 | /// ``` |
167 | /// [`Instant`]: ../../std/time/struct.Instant.html |
168 | /// [`SystemTime`]: ../../std/time/struct.SystemTime.html |
169 | #[stable (feature = "duration_saturating_ops" , since = "1.53.0" )] |
170 | pub const MAX: Duration = Duration::new(u64::MAX, NANOS_PER_SEC - 1); |
171 | |
172 | /// Creates a new `Duration` from the specified number of whole seconds and |
173 | /// additional nanoseconds. |
174 | /// |
175 | /// If the number of nanoseconds is greater than 1 billion (the number of |
176 | /// nanoseconds in a second), then it will carry over into the seconds provided. |
177 | /// |
178 | /// # Panics |
179 | /// |
180 | /// This constructor will panic if the carry from the nanoseconds overflows |
181 | /// the seconds counter. |
182 | /// |
183 | /// # Examples |
184 | /// |
185 | /// ``` |
186 | /// use std::time::Duration; |
187 | /// |
188 | /// let five_seconds = Duration::new(5, 0); |
189 | /// ``` |
190 | #[stable (feature = "duration" , since = "1.3.0" )] |
191 | #[inline ] |
192 | #[must_use ] |
193 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
194 | pub const fn new(secs: u64, nanos: u32) -> Duration { |
195 | if nanos < NANOS_PER_SEC { |
196 | // SAFETY: nanos < NANOS_PER_SEC, therefore nanos is within the valid range |
197 | Duration { secs, nanos: unsafe { Nanoseconds::new_unchecked(nanos) } } |
198 | } else { |
199 | let secs = secs |
200 | .checked_add((nanos / NANOS_PER_SEC) as u64) |
201 | .expect("overflow in Duration::new" ); |
202 | let nanos = nanos % NANOS_PER_SEC; |
203 | // SAFETY: nanos % NANOS_PER_SEC < NANOS_PER_SEC, therefore nanos is within the valid range |
204 | Duration { secs, nanos: unsafe { Nanoseconds::new_unchecked(nanos) } } |
205 | } |
206 | } |
207 | |
208 | /// Creates a new `Duration` from the specified number of whole seconds. |
209 | /// |
210 | /// # Examples |
211 | /// |
212 | /// ``` |
213 | /// use std::time::Duration; |
214 | /// |
215 | /// let duration = Duration::from_secs(5); |
216 | /// |
217 | /// assert_eq!(5, duration.as_secs()); |
218 | /// assert_eq!(0, duration.subsec_nanos()); |
219 | /// ``` |
220 | #[stable (feature = "duration" , since = "1.3.0" )] |
221 | #[must_use ] |
222 | #[inline ] |
223 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
224 | pub const fn from_secs(secs: u64) -> Duration { |
225 | Duration { secs, nanos: Nanoseconds::ZERO } |
226 | } |
227 | |
228 | /// Creates a new `Duration` from the specified number of milliseconds. |
229 | /// |
230 | /// # Examples |
231 | /// |
232 | /// ``` |
233 | /// use std::time::Duration; |
234 | /// |
235 | /// let duration = Duration::from_millis(2_569); |
236 | /// |
237 | /// assert_eq!(2, duration.as_secs()); |
238 | /// assert_eq!(569_000_000, duration.subsec_nanos()); |
239 | /// ``` |
240 | #[stable (feature = "duration" , since = "1.3.0" )] |
241 | #[must_use ] |
242 | #[inline ] |
243 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
244 | pub const fn from_millis(millis: u64) -> Duration { |
245 | let secs = millis / MILLIS_PER_SEC; |
246 | let subsec_millis = (millis % MILLIS_PER_SEC) as u32; |
247 | // SAFETY: (x % 1_000) * 1_000_000 < 1_000_000_000 |
248 | // => x % 1_000 < 1_000 |
249 | let subsec_nanos = unsafe { Nanoseconds::new_unchecked(subsec_millis * NANOS_PER_MILLI) }; |
250 | |
251 | Duration { secs, nanos: subsec_nanos } |
252 | } |
253 | |
254 | /// Creates a new `Duration` from the specified number of microseconds. |
255 | /// |
256 | /// # Examples |
257 | /// |
258 | /// ``` |
259 | /// use std::time::Duration; |
260 | /// |
261 | /// let duration = Duration::from_micros(1_000_002); |
262 | /// |
263 | /// assert_eq!(1, duration.as_secs()); |
264 | /// assert_eq!(2_000, duration.subsec_nanos()); |
265 | /// ``` |
266 | #[stable (feature = "duration_from_micros" , since = "1.27.0" )] |
267 | #[must_use ] |
268 | #[inline ] |
269 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
270 | pub const fn from_micros(micros: u64) -> Duration { |
271 | let secs = micros / MICROS_PER_SEC; |
272 | let subsec_micros = (micros % MICROS_PER_SEC) as u32; |
273 | // SAFETY: (x % 1_000_000) * 1_000 < 1_000_000_000 |
274 | // => x % 1_000_000 < 1_000_000 |
275 | let subsec_nanos = unsafe { Nanoseconds::new_unchecked(subsec_micros * NANOS_PER_MICRO) }; |
276 | |
277 | Duration { secs, nanos: subsec_nanos } |
278 | } |
279 | |
280 | /// Creates a new `Duration` from the specified number of nanoseconds. |
281 | /// |
282 | /// Note: Using this on the return value of `as_nanos()` might cause unexpected behavior: |
283 | /// `as_nanos()` returns a u128, and can return values that do not fit in u64, e.g. 585 years. |
284 | /// Instead, consider using the pattern `Duration::new(d.as_secs(), d.subsec_nanos())` |
285 | /// if you cannot copy/clone the Duration directly. |
286 | /// |
287 | /// # Examples |
288 | /// |
289 | /// ``` |
290 | /// use std::time::Duration; |
291 | /// |
292 | /// let duration = Duration::from_nanos(1_000_000_123); |
293 | /// |
294 | /// assert_eq!(1, duration.as_secs()); |
295 | /// assert_eq!(123, duration.subsec_nanos()); |
296 | /// ``` |
297 | #[stable (feature = "duration_extras" , since = "1.27.0" )] |
298 | #[must_use ] |
299 | #[inline ] |
300 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
301 | pub const fn from_nanos(nanos: u64) -> Duration { |
302 | const NANOS_PER_SEC: u64 = self::NANOS_PER_SEC as u64; |
303 | let secs = nanos / NANOS_PER_SEC; |
304 | let subsec_nanos = (nanos % NANOS_PER_SEC) as u32; |
305 | // SAFETY: x % 1_000_000_000 < 1_000_000_000 |
306 | let subsec_nanos = unsafe { Nanoseconds::new_unchecked(subsec_nanos) }; |
307 | |
308 | Duration { secs, nanos: subsec_nanos } |
309 | } |
310 | |
311 | /// Creates a new `Duration` from the specified number of weeks. |
312 | /// |
313 | /// # Panics |
314 | /// |
315 | /// Panics if the given number of weeks overflows the `Duration` size. |
316 | /// |
317 | /// # Examples |
318 | /// |
319 | /// ``` |
320 | /// #![feature(duration_constructors)] |
321 | /// use std::time::Duration; |
322 | /// |
323 | /// let duration = Duration::from_weeks(4); |
324 | /// |
325 | /// assert_eq!(4 * 7 * 24 * 60 * 60, duration.as_secs()); |
326 | /// assert_eq!(0, duration.subsec_nanos()); |
327 | /// ``` |
328 | #[unstable (feature = "duration_constructors" , issue = "120301" )] |
329 | #[must_use ] |
330 | #[inline ] |
331 | pub const fn from_weeks(weeks: u64) -> Duration { |
332 | if weeks > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR * HOURS_PER_DAY * DAYS_PER_WEEK) { |
333 | panic!("overflow in Duration::from_weeks" ); |
334 | } |
335 | |
336 | Duration::from_secs(weeks * MINS_PER_HOUR * SECS_PER_MINUTE * HOURS_PER_DAY * DAYS_PER_WEEK) |
337 | } |
338 | |
339 | /// Creates a new `Duration` from the specified number of days. |
340 | /// |
341 | /// # Panics |
342 | /// |
343 | /// Panics if the given number of days overflows the `Duration` size. |
344 | /// |
345 | /// # Examples |
346 | /// |
347 | /// ``` |
348 | /// #![feature(duration_constructors)] |
349 | /// use std::time::Duration; |
350 | /// |
351 | /// let duration = Duration::from_days(7); |
352 | /// |
353 | /// assert_eq!(7 * 24 * 60 * 60, duration.as_secs()); |
354 | /// assert_eq!(0, duration.subsec_nanos()); |
355 | /// ``` |
356 | #[unstable (feature = "duration_constructors" , issue = "120301" )] |
357 | #[must_use ] |
358 | #[inline ] |
359 | pub const fn from_days(days: u64) -> Duration { |
360 | if days > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR * HOURS_PER_DAY) { |
361 | panic!("overflow in Duration::from_days" ); |
362 | } |
363 | |
364 | Duration::from_secs(days * MINS_PER_HOUR * SECS_PER_MINUTE * HOURS_PER_DAY) |
365 | } |
366 | |
367 | /// Creates a new `Duration` from the specified number of hours. |
368 | /// |
369 | /// # Panics |
370 | /// |
371 | /// Panics if the given number of hours overflows the `Duration` size. |
372 | /// |
373 | /// # Examples |
374 | /// |
375 | /// ``` |
376 | /// #![feature(duration_constructors)] |
377 | /// use std::time::Duration; |
378 | /// |
379 | /// let duration = Duration::from_hours(6); |
380 | /// |
381 | /// assert_eq!(6 * 60 * 60, duration.as_secs()); |
382 | /// assert_eq!(0, duration.subsec_nanos()); |
383 | /// ``` |
384 | #[unstable (feature = "duration_constructors" , issue = "120301" )] |
385 | #[must_use ] |
386 | #[inline ] |
387 | pub const fn from_hours(hours: u64) -> Duration { |
388 | if hours > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR) { |
389 | panic!("overflow in Duration::from_hours" ); |
390 | } |
391 | |
392 | Duration::from_secs(hours * MINS_PER_HOUR * SECS_PER_MINUTE) |
393 | } |
394 | |
395 | /// Creates a new `Duration` from the specified number of minutes. |
396 | /// |
397 | /// # Panics |
398 | /// |
399 | /// Panics if the given number of minutes overflows the `Duration` size. |
400 | /// |
401 | /// # Examples |
402 | /// |
403 | /// ``` |
404 | /// #![feature(duration_constructors)] |
405 | /// use std::time::Duration; |
406 | /// |
407 | /// let duration = Duration::from_mins(10); |
408 | /// |
409 | /// assert_eq!(10 * 60, duration.as_secs()); |
410 | /// assert_eq!(0, duration.subsec_nanos()); |
411 | /// ``` |
412 | #[unstable (feature = "duration_constructors" , issue = "120301" )] |
413 | #[must_use ] |
414 | #[inline ] |
415 | pub const fn from_mins(mins: u64) -> Duration { |
416 | if mins > u64::MAX / SECS_PER_MINUTE { |
417 | panic!("overflow in Duration::from_mins" ); |
418 | } |
419 | |
420 | Duration::from_secs(mins * SECS_PER_MINUTE) |
421 | } |
422 | |
423 | /// Returns true if this `Duration` spans no time. |
424 | /// |
425 | /// # Examples |
426 | /// |
427 | /// ``` |
428 | /// use std::time::Duration; |
429 | /// |
430 | /// assert!(Duration::ZERO.is_zero()); |
431 | /// assert!(Duration::new(0, 0).is_zero()); |
432 | /// assert!(Duration::from_nanos(0).is_zero()); |
433 | /// assert!(Duration::from_secs(0).is_zero()); |
434 | /// |
435 | /// assert!(!Duration::new(1, 1).is_zero()); |
436 | /// assert!(!Duration::from_nanos(1).is_zero()); |
437 | /// assert!(!Duration::from_secs(1).is_zero()); |
438 | /// ``` |
439 | #[must_use ] |
440 | #[stable (feature = "duration_zero" , since = "1.53.0" )] |
441 | #[rustc_const_stable (feature = "duration_zero" , since = "1.53.0" )] |
442 | #[inline ] |
443 | pub const fn is_zero(&self) -> bool { |
444 | self.secs == 0 && self.nanos.as_inner() == 0 |
445 | } |
446 | |
447 | /// Returns the number of _whole_ seconds contained by this `Duration`. |
448 | /// |
449 | /// The returned value does not include the fractional (nanosecond) part of the |
450 | /// duration, which can be obtained using [`subsec_nanos`]. |
451 | /// |
452 | /// # Examples |
453 | /// |
454 | /// ``` |
455 | /// use std::time::Duration; |
456 | /// |
457 | /// let duration = Duration::new(5, 730_023_852); |
458 | /// assert_eq!(duration.as_secs(), 5); |
459 | /// ``` |
460 | /// |
461 | /// To determine the total number of seconds represented by the `Duration` |
462 | /// including the fractional part, use [`as_secs_f64`] or [`as_secs_f32`] |
463 | /// |
464 | /// [`as_secs_f64`]: Duration::as_secs_f64 |
465 | /// [`as_secs_f32`]: Duration::as_secs_f32 |
466 | /// [`subsec_nanos`]: Duration::subsec_nanos |
467 | #[stable (feature = "duration" , since = "1.3.0" )] |
468 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
469 | #[must_use ] |
470 | #[inline ] |
471 | pub const fn as_secs(&self) -> u64 { |
472 | self.secs |
473 | } |
474 | |
475 | /// Returns the fractional part of this `Duration`, in whole milliseconds. |
476 | /// |
477 | /// This method does **not** return the length of the duration when |
478 | /// represented by milliseconds. The returned number always represents a |
479 | /// fractional portion of a second (i.e., it is less than one thousand). |
480 | /// |
481 | /// # Examples |
482 | /// |
483 | /// ``` |
484 | /// use std::time::Duration; |
485 | /// |
486 | /// let duration = Duration::from_millis(5_432); |
487 | /// assert_eq!(duration.as_secs(), 5); |
488 | /// assert_eq!(duration.subsec_millis(), 432); |
489 | /// ``` |
490 | #[stable (feature = "duration_extras" , since = "1.27.0" )] |
491 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
492 | #[must_use ] |
493 | #[inline ] |
494 | pub const fn subsec_millis(&self) -> u32 { |
495 | self.nanos.as_inner() / NANOS_PER_MILLI |
496 | } |
497 | |
498 | /// Returns the fractional part of this `Duration`, in whole microseconds. |
499 | /// |
500 | /// This method does **not** return the length of the duration when |
501 | /// represented by microseconds. The returned number always represents a |
502 | /// fractional portion of a second (i.e., it is less than one million). |
503 | /// |
504 | /// # Examples |
505 | /// |
506 | /// ``` |
507 | /// use std::time::Duration; |
508 | /// |
509 | /// let duration = Duration::from_micros(1_234_567); |
510 | /// assert_eq!(duration.as_secs(), 1); |
511 | /// assert_eq!(duration.subsec_micros(), 234_567); |
512 | /// ``` |
513 | #[stable (feature = "duration_extras" , since = "1.27.0" )] |
514 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
515 | #[must_use ] |
516 | #[inline ] |
517 | pub const fn subsec_micros(&self) -> u32 { |
518 | self.nanos.as_inner() / NANOS_PER_MICRO |
519 | } |
520 | |
521 | /// Returns the fractional part of this `Duration`, in nanoseconds. |
522 | /// |
523 | /// This method does **not** return the length of the duration when |
524 | /// represented by nanoseconds. The returned number always represents a |
525 | /// fractional portion of a second (i.e., it is less than one billion). |
526 | /// |
527 | /// # Examples |
528 | /// |
529 | /// ``` |
530 | /// use std::time::Duration; |
531 | /// |
532 | /// let duration = Duration::from_millis(5_010); |
533 | /// assert_eq!(duration.as_secs(), 5); |
534 | /// assert_eq!(duration.subsec_nanos(), 10_000_000); |
535 | /// ``` |
536 | #[stable (feature = "duration" , since = "1.3.0" )] |
537 | #[rustc_const_stable (feature = "duration_consts" , since = "1.32.0" )] |
538 | #[must_use ] |
539 | #[inline ] |
540 | pub const fn subsec_nanos(&self) -> u32 { |
541 | self.nanos.as_inner() |
542 | } |
543 | |
544 | /// Returns the total number of whole milliseconds contained by this `Duration`. |
545 | /// |
546 | /// # Examples |
547 | /// |
548 | /// ``` |
549 | /// use std::time::Duration; |
550 | /// |
551 | /// let duration = Duration::new(5, 730_023_852); |
552 | /// assert_eq!(duration.as_millis(), 5_730); |
553 | /// ``` |
554 | #[stable (feature = "duration_as_u128" , since = "1.33.0" )] |
555 | #[rustc_const_stable (feature = "duration_as_u128" , since = "1.33.0" )] |
556 | #[must_use ] |
557 | #[inline ] |
558 | pub const fn as_millis(&self) -> u128 { |
559 | self.secs as u128 * MILLIS_PER_SEC as u128 |
560 | + (self.nanos.as_inner() / NANOS_PER_MILLI) as u128 |
561 | } |
562 | |
563 | /// Returns the total number of whole microseconds contained by this `Duration`. |
564 | /// |
565 | /// # Examples |
566 | /// |
567 | /// ``` |
568 | /// use std::time::Duration; |
569 | /// |
570 | /// let duration = Duration::new(5, 730_023_852); |
571 | /// assert_eq!(duration.as_micros(), 5_730_023); |
572 | /// ``` |
573 | #[stable (feature = "duration_as_u128" , since = "1.33.0" )] |
574 | #[rustc_const_stable (feature = "duration_as_u128" , since = "1.33.0" )] |
575 | #[must_use ] |
576 | #[inline ] |
577 | pub const fn as_micros(&self) -> u128 { |
578 | self.secs as u128 * MICROS_PER_SEC as u128 |
579 | + (self.nanos.as_inner() / NANOS_PER_MICRO) as u128 |
580 | } |
581 | |
582 | /// Returns the total number of nanoseconds contained by this `Duration`. |
583 | /// |
584 | /// # Examples |
585 | /// |
586 | /// ``` |
587 | /// use std::time::Duration; |
588 | /// |
589 | /// let duration = Duration::new(5, 730_023_852); |
590 | /// assert_eq!(duration.as_nanos(), 5_730_023_852); |
591 | /// ``` |
592 | #[stable (feature = "duration_as_u128" , since = "1.33.0" )] |
593 | #[rustc_const_stable (feature = "duration_as_u128" , since = "1.33.0" )] |
594 | #[must_use ] |
595 | #[inline ] |
596 | pub const fn as_nanos(&self) -> u128 { |
597 | self.secs as u128 * NANOS_PER_SEC as u128 + self.nanos.as_inner() as u128 |
598 | } |
599 | |
600 | /// Computes the absolute difference between `self` and `other`. |
601 | /// |
602 | /// # Examples |
603 | /// |
604 | /// ``` |
605 | /// use std::time::Duration; |
606 | /// |
607 | /// assert_eq!(Duration::new(100, 0).abs_diff(Duration::new(80, 0)), Duration::new(20, 0)); |
608 | /// assert_eq!(Duration::new(100, 400_000_000).abs_diff(Duration::new(110, 0)), Duration::new(9, 600_000_000)); |
609 | /// ``` |
610 | #[stable (feature = "duration_abs_diff" , since = "1.81.0" )] |
611 | #[rustc_const_stable (feature = "duration_abs_diff" , since = "1.81.0" )] |
612 | #[must_use = "this returns the result of the operation, \ |
613 | without modifying the original" ] |
614 | #[inline ] |
615 | pub const fn abs_diff(self, other: Duration) -> Duration { |
616 | if let Some(res) = self.checked_sub(other) { res } else { other.checked_sub(self).unwrap() } |
617 | } |
618 | |
619 | /// Checked `Duration` addition. Computes `self + other`, returning [`None`] |
620 | /// if overflow occurred. |
621 | /// |
622 | /// # Examples |
623 | /// |
624 | /// ``` |
625 | /// use std::time::Duration; |
626 | /// |
627 | /// assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1))); |
628 | /// assert_eq!(Duration::new(1, 0).checked_add(Duration::new(u64::MAX, 0)), None); |
629 | /// ``` |
630 | #[stable (feature = "duration_checked_ops" , since = "1.16.0" )] |
631 | #[must_use = "this returns the result of the operation, \ |
632 | without modifying the original" ] |
633 | #[inline ] |
634 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
635 | pub const fn checked_add(self, rhs: Duration) -> Option<Duration> { |
636 | if let Some(mut secs) = self.secs.checked_add(rhs.secs) { |
637 | let mut nanos = self.nanos.as_inner() + rhs.nanos.as_inner(); |
638 | if nanos >= NANOS_PER_SEC { |
639 | nanos -= NANOS_PER_SEC; |
640 | if let Some(new_secs) = secs.checked_add(1) { |
641 | secs = new_secs; |
642 | } else { |
643 | return None; |
644 | } |
645 | } |
646 | debug_assert!(nanos < NANOS_PER_SEC); |
647 | Some(Duration::new(secs, nanos)) |
648 | } else { |
649 | None |
650 | } |
651 | } |
652 | |
653 | /// Saturating `Duration` addition. Computes `self + other`, returning [`Duration::MAX`] |
654 | /// if overflow occurred. |
655 | /// |
656 | /// # Examples |
657 | /// |
658 | /// ``` |
659 | /// #![feature(duration_constants)] |
660 | /// use std::time::Duration; |
661 | /// |
662 | /// assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1)); |
663 | /// assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX); |
664 | /// ``` |
665 | #[stable (feature = "duration_saturating_ops" , since = "1.53.0" )] |
666 | #[must_use = "this returns the result of the operation, \ |
667 | without modifying the original" ] |
668 | #[inline ] |
669 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
670 | pub const fn saturating_add(self, rhs: Duration) -> Duration { |
671 | match self.checked_add(rhs) { |
672 | Some(res) => res, |
673 | None => Duration::MAX, |
674 | } |
675 | } |
676 | |
677 | /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`] |
678 | /// if the result would be negative or if overflow occurred. |
679 | /// |
680 | /// # Examples |
681 | /// |
682 | /// ``` |
683 | /// use std::time::Duration; |
684 | /// |
685 | /// assert_eq!(Duration::new(0, 1).checked_sub(Duration::new(0, 0)), Some(Duration::new(0, 1))); |
686 | /// assert_eq!(Duration::new(0, 0).checked_sub(Duration::new(0, 1)), None); |
687 | /// ``` |
688 | #[stable (feature = "duration_checked_ops" , since = "1.16.0" )] |
689 | #[must_use = "this returns the result of the operation, \ |
690 | without modifying the original" ] |
691 | #[inline ] |
692 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
693 | pub const fn checked_sub(self, rhs: Duration) -> Option<Duration> { |
694 | if let Some(mut secs) = self.secs.checked_sub(rhs.secs) { |
695 | let nanos = if self.nanos.as_inner() >= rhs.nanos.as_inner() { |
696 | self.nanos.as_inner() - rhs.nanos.as_inner() |
697 | } else if let Some(sub_secs) = secs.checked_sub(1) { |
698 | secs = sub_secs; |
699 | self.nanos.as_inner() + NANOS_PER_SEC - rhs.nanos.as_inner() |
700 | } else { |
701 | return None; |
702 | }; |
703 | debug_assert!(nanos < NANOS_PER_SEC); |
704 | Some(Duration::new(secs, nanos)) |
705 | } else { |
706 | None |
707 | } |
708 | } |
709 | |
710 | /// Saturating `Duration` subtraction. Computes `self - other`, returning [`Duration::ZERO`] |
711 | /// if the result would be negative or if overflow occurred. |
712 | /// |
713 | /// # Examples |
714 | /// |
715 | /// ``` |
716 | /// use std::time::Duration; |
717 | /// |
718 | /// assert_eq!(Duration::new(0, 1).saturating_sub(Duration::new(0, 0)), Duration::new(0, 1)); |
719 | /// assert_eq!(Duration::new(0, 0).saturating_sub(Duration::new(0, 1)), Duration::ZERO); |
720 | /// ``` |
721 | #[stable (feature = "duration_saturating_ops" , since = "1.53.0" )] |
722 | #[must_use = "this returns the result of the operation, \ |
723 | without modifying the original" ] |
724 | #[inline ] |
725 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
726 | pub const fn saturating_sub(self, rhs: Duration) -> Duration { |
727 | match self.checked_sub(rhs) { |
728 | Some(res) => res, |
729 | None => Duration::ZERO, |
730 | } |
731 | } |
732 | |
733 | /// Checked `Duration` multiplication. Computes `self * other`, returning |
734 | /// [`None`] if overflow occurred. |
735 | /// |
736 | /// # Examples |
737 | /// |
738 | /// ``` |
739 | /// use std::time::Duration; |
740 | /// |
741 | /// assert_eq!(Duration::new(0, 500_000_001).checked_mul(2), Some(Duration::new(1, 2))); |
742 | /// assert_eq!(Duration::new(u64::MAX - 1, 0).checked_mul(2), None); |
743 | /// ``` |
744 | #[stable (feature = "duration_checked_ops" , since = "1.16.0" )] |
745 | #[must_use = "this returns the result of the operation, \ |
746 | without modifying the original" ] |
747 | #[inline ] |
748 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
749 | pub const fn checked_mul(self, rhs: u32) -> Option<Duration> { |
750 | // Multiply nanoseconds as u64, because it cannot overflow that way. |
751 | let total_nanos = self.nanos.as_inner() as u64 * rhs as u64; |
752 | let extra_secs = total_nanos / (NANOS_PER_SEC as u64); |
753 | let nanos = (total_nanos % (NANOS_PER_SEC as u64)) as u32; |
754 | // FIXME(const-hack): use `and_then` once that is possible. |
755 | if let Some(s) = self.secs.checked_mul(rhs as u64) { |
756 | if let Some(secs) = s.checked_add(extra_secs) { |
757 | debug_assert!(nanos < NANOS_PER_SEC); |
758 | return Some(Duration::new(secs, nanos)); |
759 | } |
760 | } |
761 | None |
762 | } |
763 | |
764 | /// Saturating `Duration` multiplication. Computes `self * other`, returning |
765 | /// [`Duration::MAX`] if overflow occurred. |
766 | /// |
767 | /// # Examples |
768 | /// |
769 | /// ``` |
770 | /// #![feature(duration_constants)] |
771 | /// use std::time::Duration; |
772 | /// |
773 | /// assert_eq!(Duration::new(0, 500_000_001).saturating_mul(2), Duration::new(1, 2)); |
774 | /// assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX); |
775 | /// ``` |
776 | #[stable (feature = "duration_saturating_ops" , since = "1.53.0" )] |
777 | #[must_use = "this returns the result of the operation, \ |
778 | without modifying the original" ] |
779 | #[inline ] |
780 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
781 | pub const fn saturating_mul(self, rhs: u32) -> Duration { |
782 | match self.checked_mul(rhs) { |
783 | Some(res) => res, |
784 | None => Duration::MAX, |
785 | } |
786 | } |
787 | |
788 | /// Checked `Duration` division. Computes `self / other`, returning [`None`] |
789 | /// if `other == 0`. |
790 | /// |
791 | /// # Examples |
792 | /// |
793 | /// ``` |
794 | /// use std::time::Duration; |
795 | /// |
796 | /// assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0))); |
797 | /// assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000))); |
798 | /// assert_eq!(Duration::new(2, 0).checked_div(0), None); |
799 | /// ``` |
800 | #[stable (feature = "duration_checked_ops" , since = "1.16.0" )] |
801 | #[must_use = "this returns the result of the operation, \ |
802 | without modifying the original" ] |
803 | #[inline ] |
804 | #[rustc_const_stable (feature = "duration_consts_2" , since = "1.58.0" )] |
805 | pub const fn checked_div(self, rhs: u32) -> Option<Duration> { |
806 | if rhs != 0 { |
807 | let (secs, extra_secs) = (self.secs / (rhs as u64), self.secs % (rhs as u64)); |
808 | let (mut nanos, extra_nanos) = |
809 | (self.nanos.as_inner() / rhs, self.nanos.as_inner() % rhs); |
810 | nanos += |
811 | ((extra_secs * (NANOS_PER_SEC as u64) + extra_nanos as u64) / (rhs as u64)) as u32; |
812 | debug_assert!(nanos < NANOS_PER_SEC); |
813 | Some(Duration::new(secs, nanos)) |
814 | } else { |
815 | None |
816 | } |
817 | } |
818 | |
819 | /// Returns the number of seconds contained by this `Duration` as `f64`. |
820 | /// |
821 | /// The returned value includes the fractional (nanosecond) part of the duration. |
822 | /// |
823 | /// # Examples |
824 | /// ``` |
825 | /// use std::time::Duration; |
826 | /// |
827 | /// let dur = Duration::new(2, 700_000_000); |
828 | /// assert_eq!(dur.as_secs_f64(), 2.7); |
829 | /// ``` |
830 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
831 | #[must_use ] |
832 | #[inline ] |
833 | #[rustc_const_stable (feature = "duration_consts_float" , since = "1.83.0" )] |
834 | pub const fn as_secs_f64(&self) -> f64 { |
835 | (self.secs as f64) + (self.nanos.as_inner() as f64) / (NANOS_PER_SEC as f64) |
836 | } |
837 | |
838 | /// Returns the number of seconds contained by this `Duration` as `f32`. |
839 | /// |
840 | /// The returned value includes the fractional (nanosecond) part of the duration. |
841 | /// |
842 | /// # Examples |
843 | /// ``` |
844 | /// use std::time::Duration; |
845 | /// |
846 | /// let dur = Duration::new(2, 700_000_000); |
847 | /// assert_eq!(dur.as_secs_f32(), 2.7); |
848 | /// ``` |
849 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
850 | #[must_use ] |
851 | #[inline ] |
852 | #[rustc_const_stable (feature = "duration_consts_float" , since = "1.83.0" )] |
853 | pub const fn as_secs_f32(&self) -> f32 { |
854 | (self.secs as f32) + (self.nanos.as_inner() as f32) / (NANOS_PER_SEC as f32) |
855 | } |
856 | |
857 | /// Returns the number of milliseconds contained by this `Duration` as `f64`. |
858 | /// |
859 | /// The returned value includes the fractional (nanosecond) part of the duration. |
860 | /// |
861 | /// # Examples |
862 | /// ``` |
863 | /// #![feature(duration_millis_float)] |
864 | /// use std::time::Duration; |
865 | /// |
866 | /// let dur = Duration::new(2, 345_678_000); |
867 | /// assert_eq!(dur.as_millis_f64(), 2_345.678); |
868 | /// ``` |
869 | #[unstable (feature = "duration_millis_float" , issue = "122451" )] |
870 | #[must_use ] |
871 | #[inline ] |
872 | pub const fn as_millis_f64(&self) -> f64 { |
873 | (self.secs as f64) * (MILLIS_PER_SEC as f64) |
874 | + (self.nanos.as_inner() as f64) / (NANOS_PER_MILLI as f64) |
875 | } |
876 | |
877 | /// Returns the number of milliseconds contained by this `Duration` as `f32`. |
878 | /// |
879 | /// The returned value includes the fractional (nanosecond) part of the duration. |
880 | /// |
881 | /// # Examples |
882 | /// ``` |
883 | /// #![feature(duration_millis_float)] |
884 | /// use std::time::Duration; |
885 | /// |
886 | /// let dur = Duration::new(2, 345_678_000); |
887 | /// assert_eq!(dur.as_millis_f32(), 2_345.678); |
888 | /// ``` |
889 | #[unstable (feature = "duration_millis_float" , issue = "122451" )] |
890 | #[must_use ] |
891 | #[inline ] |
892 | pub const fn as_millis_f32(&self) -> f32 { |
893 | (self.secs as f32) * (MILLIS_PER_SEC as f32) |
894 | + (self.nanos.as_inner() as f32) / (NANOS_PER_MILLI as f32) |
895 | } |
896 | |
897 | /// Creates a new `Duration` from the specified number of seconds represented |
898 | /// as `f64`. |
899 | /// |
900 | /// # Panics |
901 | /// This constructor will panic if `secs` is negative, overflows `Duration` or not finite. |
902 | /// |
903 | /// # Examples |
904 | /// ``` |
905 | /// use std::time::Duration; |
906 | /// |
907 | /// let res = Duration::from_secs_f64(0.0); |
908 | /// assert_eq!(res, Duration::new(0, 0)); |
909 | /// let res = Duration::from_secs_f64(1e-20); |
910 | /// assert_eq!(res, Duration::new(0, 0)); |
911 | /// let res = Duration::from_secs_f64(4.2e-7); |
912 | /// assert_eq!(res, Duration::new(0, 420)); |
913 | /// let res = Duration::from_secs_f64(2.7); |
914 | /// assert_eq!(res, Duration::new(2, 700_000_000)); |
915 | /// let res = Duration::from_secs_f64(3e10); |
916 | /// assert_eq!(res, Duration::new(30_000_000_000, 0)); |
917 | /// // subnormal float |
918 | /// let res = Duration::from_secs_f64(f64::from_bits(1)); |
919 | /// assert_eq!(res, Duration::new(0, 0)); |
920 | /// // conversion uses rounding |
921 | /// let res = Duration::from_secs_f64(0.999e-9); |
922 | /// assert_eq!(res, Duration::new(0, 1)); |
923 | /// ``` |
924 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
925 | #[must_use ] |
926 | #[inline ] |
927 | pub fn from_secs_f64(secs: f64) -> Duration { |
928 | match Duration::try_from_secs_f64(secs) { |
929 | Ok(v) => v, |
930 | Err(e) => panic!("{}" , e.description()), |
931 | } |
932 | } |
933 | |
934 | /// Creates a new `Duration` from the specified number of seconds represented |
935 | /// as `f32`. |
936 | /// |
937 | /// # Panics |
938 | /// This constructor will panic if `secs` is negative, overflows `Duration` or not finite. |
939 | /// |
940 | /// # Examples |
941 | /// ``` |
942 | /// use std::time::Duration; |
943 | /// |
944 | /// let res = Duration::from_secs_f32(0.0); |
945 | /// assert_eq!(res, Duration::new(0, 0)); |
946 | /// let res = Duration::from_secs_f32(1e-20); |
947 | /// assert_eq!(res, Duration::new(0, 0)); |
948 | /// let res = Duration::from_secs_f32(4.2e-7); |
949 | /// assert_eq!(res, Duration::new(0, 420)); |
950 | /// let res = Duration::from_secs_f32(2.7); |
951 | /// assert_eq!(res, Duration::new(2, 700_000_048)); |
952 | /// let res = Duration::from_secs_f32(3e10); |
953 | /// assert_eq!(res, Duration::new(30_000_001_024, 0)); |
954 | /// // subnormal float |
955 | /// let res = Duration::from_secs_f32(f32::from_bits(1)); |
956 | /// assert_eq!(res, Duration::new(0, 0)); |
957 | /// // conversion uses rounding |
958 | /// let res = Duration::from_secs_f32(0.999e-9); |
959 | /// assert_eq!(res, Duration::new(0, 1)); |
960 | /// ``` |
961 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
962 | #[must_use ] |
963 | #[inline ] |
964 | pub fn from_secs_f32(secs: f32) -> Duration { |
965 | match Duration::try_from_secs_f32(secs) { |
966 | Ok(v) => v, |
967 | Err(e) => panic!("{}" , e.description()), |
968 | } |
969 | } |
970 | |
971 | /// Multiplies `Duration` by `f64`. |
972 | /// |
973 | /// # Panics |
974 | /// This method will panic if result is negative, overflows `Duration` or not finite. |
975 | /// |
976 | /// # Examples |
977 | /// ``` |
978 | /// use std::time::Duration; |
979 | /// |
980 | /// let dur = Duration::new(2, 700_000_000); |
981 | /// assert_eq!(dur.mul_f64(3.14), Duration::new(8, 478_000_000)); |
982 | /// assert_eq!(dur.mul_f64(3.14e5), Duration::new(847_800, 0)); |
983 | /// ``` |
984 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
985 | #[must_use = "this returns the result of the operation, \ |
986 | without modifying the original" ] |
987 | #[inline ] |
988 | pub fn mul_f64(self, rhs: f64) -> Duration { |
989 | Duration::from_secs_f64(rhs * self.as_secs_f64()) |
990 | } |
991 | |
992 | /// Multiplies `Duration` by `f32`. |
993 | /// |
994 | /// # Panics |
995 | /// This method will panic if result is negative, overflows `Duration` or not finite. |
996 | /// |
997 | /// # Examples |
998 | /// ``` |
999 | /// use std::time::Duration; |
1000 | /// |
1001 | /// let dur = Duration::new(2, 700_000_000); |
1002 | /// assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_641)); |
1003 | /// assert_eq!(dur.mul_f32(3.14e5), Duration::new(847_800, 0)); |
1004 | /// ``` |
1005 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
1006 | #[must_use = "this returns the result of the operation, \ |
1007 | without modifying the original" ] |
1008 | #[inline ] |
1009 | pub fn mul_f32(self, rhs: f32) -> Duration { |
1010 | Duration::from_secs_f32(rhs * self.as_secs_f32()) |
1011 | } |
1012 | |
1013 | /// Divides `Duration` by `f64`. |
1014 | /// |
1015 | /// # Panics |
1016 | /// This method will panic if result is negative, overflows `Duration` or not finite. |
1017 | /// |
1018 | /// # Examples |
1019 | /// ``` |
1020 | /// use std::time::Duration; |
1021 | /// |
1022 | /// let dur = Duration::new(2, 700_000_000); |
1023 | /// assert_eq!(dur.div_f64(3.14), Duration::new(0, 859_872_611)); |
1024 | /// assert_eq!(dur.div_f64(3.14e5), Duration::new(0, 8_599)); |
1025 | /// ``` |
1026 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
1027 | #[must_use = "this returns the result of the operation, \ |
1028 | without modifying the original" ] |
1029 | #[inline ] |
1030 | pub fn div_f64(self, rhs: f64) -> Duration { |
1031 | Duration::from_secs_f64(self.as_secs_f64() / rhs) |
1032 | } |
1033 | |
1034 | /// Divides `Duration` by `f32`. |
1035 | /// |
1036 | /// # Panics |
1037 | /// This method will panic if result is negative, overflows `Duration` or not finite. |
1038 | /// |
1039 | /// # Examples |
1040 | /// ``` |
1041 | /// use std::time::Duration; |
1042 | /// |
1043 | /// let dur = Duration::new(2, 700_000_000); |
1044 | /// // note that due to rounding errors result is slightly |
1045 | /// // different from 0.859_872_611 |
1046 | /// assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_580)); |
1047 | /// assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_599)); |
1048 | /// ``` |
1049 | #[stable (feature = "duration_float" , since = "1.38.0" )] |
1050 | #[must_use = "this returns the result of the operation, \ |
1051 | without modifying the original" ] |
1052 | #[inline ] |
1053 | pub fn div_f32(self, rhs: f32) -> Duration { |
1054 | Duration::from_secs_f32(self.as_secs_f32() / rhs) |
1055 | } |
1056 | |
1057 | /// Divides `Duration` by `Duration` and returns `f64`. |
1058 | /// |
1059 | /// # Examples |
1060 | /// ``` |
1061 | /// use std::time::Duration; |
1062 | /// |
1063 | /// let dur1 = Duration::new(2, 700_000_000); |
1064 | /// let dur2 = Duration::new(5, 400_000_000); |
1065 | /// assert_eq!(dur1.div_duration_f64(dur2), 0.5); |
1066 | /// ``` |
1067 | #[stable (feature = "div_duration" , since = "1.80.0" )] |
1068 | #[must_use = "this returns the result of the operation, \ |
1069 | without modifying the original" ] |
1070 | #[inline ] |
1071 | #[rustc_const_stable (feature = "duration_consts_float" , since = "1.83.0" )] |
1072 | pub const fn div_duration_f64(self, rhs: Duration) -> f64 { |
1073 | let self_nanos = |
1074 | (self.secs as f64) * (NANOS_PER_SEC as f64) + (self.nanos.as_inner() as f64); |
1075 | let rhs_nanos = (rhs.secs as f64) * (NANOS_PER_SEC as f64) + (rhs.nanos.as_inner() as f64); |
1076 | self_nanos / rhs_nanos |
1077 | } |
1078 | |
1079 | /// Divides `Duration` by `Duration` and returns `f32`. |
1080 | /// |
1081 | /// # Examples |
1082 | /// ``` |
1083 | /// use std::time::Duration; |
1084 | /// |
1085 | /// let dur1 = Duration::new(2, 700_000_000); |
1086 | /// let dur2 = Duration::new(5, 400_000_000); |
1087 | /// assert_eq!(dur1.div_duration_f32(dur2), 0.5); |
1088 | /// ``` |
1089 | #[stable (feature = "div_duration" , since = "1.80.0" )] |
1090 | #[must_use = "this returns the result of the operation, \ |
1091 | without modifying the original" ] |
1092 | #[inline ] |
1093 | #[rustc_const_stable (feature = "duration_consts_float" , since = "1.83.0" )] |
1094 | pub const fn div_duration_f32(self, rhs: Duration) -> f32 { |
1095 | let self_nanos = |
1096 | (self.secs as f32) * (NANOS_PER_SEC as f32) + (self.nanos.as_inner() as f32); |
1097 | let rhs_nanos = (rhs.secs as f32) * (NANOS_PER_SEC as f32) + (rhs.nanos.as_inner() as f32); |
1098 | self_nanos / rhs_nanos |
1099 | } |
1100 | } |
1101 | |
1102 | #[stable (feature = "duration" , since = "1.3.0" )] |
1103 | impl Add for Duration { |
1104 | type Output = Duration; |
1105 | |
1106 | #[inline ] |
1107 | fn add(self, rhs: Duration) -> Duration { |
1108 | self.checked_add(rhs).expect(msg:"overflow when adding durations" ) |
1109 | } |
1110 | } |
1111 | |
1112 | #[stable (feature = "time_augmented_assignment" , since = "1.9.0" )] |
1113 | impl AddAssign for Duration { |
1114 | #[inline ] |
1115 | fn add_assign(&mut self, rhs: Duration) { |
1116 | *self = *self + rhs; |
1117 | } |
1118 | } |
1119 | |
1120 | #[stable (feature = "duration" , since = "1.3.0" )] |
1121 | impl Sub for Duration { |
1122 | type Output = Duration; |
1123 | |
1124 | #[inline ] |
1125 | fn sub(self, rhs: Duration) -> Duration { |
1126 | self.checked_sub(rhs).expect(msg:"overflow when subtracting durations" ) |
1127 | } |
1128 | } |
1129 | |
1130 | #[stable (feature = "time_augmented_assignment" , since = "1.9.0" )] |
1131 | impl SubAssign for Duration { |
1132 | #[inline ] |
1133 | fn sub_assign(&mut self, rhs: Duration) { |
1134 | *self = *self - rhs; |
1135 | } |
1136 | } |
1137 | |
1138 | #[stable (feature = "duration" , since = "1.3.0" )] |
1139 | impl Mul<u32> for Duration { |
1140 | type Output = Duration; |
1141 | |
1142 | #[inline ] |
1143 | fn mul(self, rhs: u32) -> Duration { |
1144 | self.checked_mul(rhs).expect(msg:"overflow when multiplying duration by scalar" ) |
1145 | } |
1146 | } |
1147 | |
1148 | #[stable (feature = "symmetric_u32_duration_mul" , since = "1.31.0" )] |
1149 | impl Mul<Duration> for u32 { |
1150 | type Output = Duration; |
1151 | |
1152 | #[inline ] |
1153 | fn mul(self, rhs: Duration) -> Duration { |
1154 | rhs * self |
1155 | } |
1156 | } |
1157 | |
1158 | #[stable (feature = "time_augmented_assignment" , since = "1.9.0" )] |
1159 | impl MulAssign<u32> for Duration { |
1160 | #[inline ] |
1161 | fn mul_assign(&mut self, rhs: u32) { |
1162 | *self = *self * rhs; |
1163 | } |
1164 | } |
1165 | |
1166 | #[stable (feature = "duration" , since = "1.3.0" )] |
1167 | impl Div<u32> for Duration { |
1168 | type Output = Duration; |
1169 | |
1170 | #[inline ] |
1171 | #[track_caller ] |
1172 | fn div(self, rhs: u32) -> Duration { |
1173 | self.checked_div(rhs).expect(msg:"divide by zero error when dividing duration by scalar" ) |
1174 | } |
1175 | } |
1176 | |
1177 | #[stable (feature = "time_augmented_assignment" , since = "1.9.0" )] |
1178 | impl DivAssign<u32> for Duration { |
1179 | #[inline ] |
1180 | #[track_caller ] |
1181 | fn div_assign(&mut self, rhs: u32) { |
1182 | *self = *self / rhs; |
1183 | } |
1184 | } |
1185 | |
1186 | macro_rules! sum_durations { |
1187 | ($iter:expr) => {{ |
1188 | let mut total_secs: u64 = 0; |
1189 | let mut total_nanos: u64 = 0; |
1190 | |
1191 | for entry in $iter { |
1192 | total_secs = |
1193 | total_secs.checked_add(entry.secs).expect("overflow in iter::sum over durations" ); |
1194 | total_nanos = match total_nanos.checked_add(entry.nanos.as_inner() as u64) { |
1195 | Some(n) => n, |
1196 | None => { |
1197 | total_secs = total_secs |
1198 | .checked_add(total_nanos / NANOS_PER_SEC as u64) |
1199 | .expect("overflow in iter::sum over durations" ); |
1200 | (total_nanos % NANOS_PER_SEC as u64) + entry.nanos.as_inner() as u64 |
1201 | } |
1202 | }; |
1203 | } |
1204 | total_secs = total_secs |
1205 | .checked_add(total_nanos / NANOS_PER_SEC as u64) |
1206 | .expect("overflow in iter::sum over durations" ); |
1207 | total_nanos = total_nanos % NANOS_PER_SEC as u64; |
1208 | Duration::new(total_secs, total_nanos as u32) |
1209 | }}; |
1210 | } |
1211 | |
1212 | #[stable (feature = "duration_sum" , since = "1.16.0" )] |
1213 | impl Sum for Duration { |
1214 | fn sum<I: Iterator<Item = Duration>>(iter: I) -> Duration { |
1215 | sum_durations!(iter) |
1216 | } |
1217 | } |
1218 | |
1219 | #[stable (feature = "duration_sum" , since = "1.16.0" )] |
1220 | impl<'a> Sum<&'a Duration> for Duration { |
1221 | fn sum<I: Iterator<Item = &'a Duration>>(iter: I) -> Duration { |
1222 | sum_durations!(iter) |
1223 | } |
1224 | } |
1225 | |
1226 | #[stable (feature = "duration_debug_impl" , since = "1.27.0" )] |
1227 | impl fmt::Debug for Duration { |
1228 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
1229 | /// Formats a floating point number in decimal notation. |
1230 | /// |
1231 | /// The number is given as the `integer_part` and a fractional part. |
1232 | /// The value of the fractional part is `fractional_part / divisor`. So |
1233 | /// `integer_part` = 3, `fractional_part` = 12 and `divisor` = 100 |
1234 | /// represents the number `3.012`. Trailing zeros are omitted. |
1235 | /// |
1236 | /// `divisor` must not be above 100_000_000. It also should be a power |
1237 | /// of 10, everything else doesn't make sense. `fractional_part` has |
1238 | /// to be less than `10 * divisor`! |
1239 | /// |
1240 | /// A prefix and postfix may be added. The whole thing is padded |
1241 | /// to the formatter's `width`, if specified. |
1242 | fn fmt_decimal( |
1243 | f: &mut fmt::Formatter<'_>, |
1244 | integer_part: u64, |
1245 | mut fractional_part: u32, |
1246 | mut divisor: u32, |
1247 | prefix: &str, |
1248 | postfix: &str, |
1249 | ) -> fmt::Result { |
1250 | // Encode the fractional part into a temporary buffer. The buffer |
1251 | // only need to hold 9 elements, because `fractional_part` has to |
1252 | // be smaller than 10^9. The buffer is prefilled with '0' digits |
1253 | // to simplify the code below. |
1254 | let mut buf = [b'0' ; 9]; |
1255 | |
1256 | // The next digit is written at this position |
1257 | let mut pos = 0; |
1258 | |
1259 | // We keep writing digits into the buffer while there are non-zero |
1260 | // digits left and we haven't written enough digits yet. |
1261 | while fractional_part > 0 && pos < f.precision().unwrap_or(9) { |
1262 | // Write new digit into the buffer |
1263 | buf[pos] = b'0' + (fractional_part / divisor) as u8; |
1264 | |
1265 | fractional_part %= divisor; |
1266 | divisor /= 10; |
1267 | pos += 1; |
1268 | } |
1269 | |
1270 | // If a precision < 9 was specified, there may be some non-zero |
1271 | // digits left that weren't written into the buffer. In that case we |
1272 | // need to perform rounding to match the semantics of printing |
1273 | // normal floating point numbers. However, we only need to do work |
1274 | // when rounding up. This happens if the first digit of the |
1275 | // remaining ones is >= 5. |
1276 | let integer_part = if fractional_part > 0 && fractional_part >= divisor * 5 { |
1277 | // Round up the number contained in the buffer. We go through |
1278 | // the buffer backwards and keep track of the carry. |
1279 | let mut rev_pos = pos; |
1280 | let mut carry = true; |
1281 | while carry && rev_pos > 0 { |
1282 | rev_pos -= 1; |
1283 | |
1284 | // If the digit in the buffer is not '9', we just need to |
1285 | // increment it and can stop then (since we don't have a |
1286 | // carry anymore). Otherwise, we set it to '0' (overflow) |
1287 | // and continue. |
1288 | if buf[rev_pos] < b'9' { |
1289 | buf[rev_pos] += 1; |
1290 | carry = false; |
1291 | } else { |
1292 | buf[rev_pos] = b'0' ; |
1293 | } |
1294 | } |
1295 | |
1296 | // If we still have the carry bit set, that means that we set |
1297 | // the whole buffer to '0's and need to increment the integer |
1298 | // part. |
1299 | if carry { |
1300 | // If `integer_part == u64::MAX` and precision < 9, any |
1301 | // carry of the overflow during rounding of the |
1302 | // `fractional_part` into the `integer_part` will cause the |
1303 | // `integer_part` itself to overflow. Avoid this by using an |
1304 | // `Option<u64>`, with `None` representing `u64::MAX + 1`. |
1305 | integer_part.checked_add(1) |
1306 | } else { |
1307 | Some(integer_part) |
1308 | } |
1309 | } else { |
1310 | Some(integer_part) |
1311 | }; |
1312 | |
1313 | // Determine the end of the buffer: if precision is set, we just |
1314 | // use as many digits from the buffer (capped to 9). If it isn't |
1315 | // set, we only use all digits up to the last non-zero one. |
1316 | let end = f.precision().map(|p| crate::cmp::min(p, 9)).unwrap_or(pos); |
1317 | |
1318 | // This closure emits the formatted duration without emitting any |
1319 | // padding (padding is calculated below). |
1320 | let emit_without_padding = |f: &mut fmt::Formatter<'_>| { |
1321 | if let Some(integer_part) = integer_part { |
1322 | write!(f, " {}{}" , prefix, integer_part)?; |
1323 | } else { |
1324 | // u64::MAX + 1 == 18446744073709551616 |
1325 | write!(f, " {}18446744073709551616" , prefix)?; |
1326 | } |
1327 | |
1328 | // Write the decimal point and the fractional part (if any). |
1329 | if end > 0 { |
1330 | // SAFETY: We are only writing ASCII digits into the buffer and |
1331 | // it was initialized with '0's, so it contains valid UTF8. |
1332 | let s = unsafe { crate::str::from_utf8_unchecked(&buf[..end]) }; |
1333 | |
1334 | // If the user request a precision > 9, we pad '0's at the end. |
1335 | let w = f.precision().unwrap_or(pos); |
1336 | write!(f, ". {:0<width$}" , s, width = w)?; |
1337 | } |
1338 | |
1339 | write!(f, " {}" , postfix) |
1340 | }; |
1341 | |
1342 | match f.width() { |
1343 | None => { |
1344 | // No `width` specified. There's no need to calculate the |
1345 | // length of the output in this case, just emit it. |
1346 | emit_without_padding(f) |
1347 | } |
1348 | Some(requested_w) => { |
1349 | // A `width` was specified. Calculate the actual width of |
1350 | // the output in order to calculate the required padding. |
1351 | // It consists of 4 parts: |
1352 | // 1. The prefix: is either "+" or "", so we can just use len(). |
1353 | // 2. The postfix: can be "µs" so we have to count UTF8 characters. |
1354 | let mut actual_w = prefix.len() + postfix.chars().count(); |
1355 | // 3. The integer part: |
1356 | if let Some(integer_part) = integer_part { |
1357 | if let Some(log) = integer_part.checked_ilog10() { |
1358 | // integer_part is > 0, so has length log10(x)+1 |
1359 | actual_w += 1 + log as usize; |
1360 | } else { |
1361 | // integer_part is 0, so has length 1. |
1362 | actual_w += 1; |
1363 | } |
1364 | } else { |
1365 | // integer_part is u64::MAX + 1, so has length 20 |
1366 | actual_w += 20; |
1367 | } |
1368 | // 4. The fractional part (if any): |
1369 | if end > 0 { |
1370 | let frac_part_w = f.precision().unwrap_or(pos); |
1371 | actual_w += 1 + frac_part_w; |
1372 | } |
1373 | |
1374 | if requested_w <= actual_w { |
1375 | // Output is already longer than `width`, so don't pad. |
1376 | emit_without_padding(f) |
1377 | } else { |
1378 | // We need to add padding. Use the `Formatter::padding` helper function. |
1379 | let default_align = fmt::Alignment::Left; |
1380 | let post_padding = |
1381 | f.padding((requested_w - actual_w) as u16, default_align)?; |
1382 | emit_without_padding(f)?; |
1383 | post_padding.write(f) |
1384 | } |
1385 | } |
1386 | } |
1387 | } |
1388 | |
1389 | // Print leading '+' sign if requested |
1390 | let prefix = if f.sign_plus() { "+" } else { "" }; |
1391 | |
1392 | if self.secs > 0 { |
1393 | fmt_decimal(f, self.secs, self.nanos.as_inner(), NANOS_PER_SEC / 10, prefix, "s" ) |
1394 | } else if self.nanos.as_inner() >= NANOS_PER_MILLI { |
1395 | fmt_decimal( |
1396 | f, |
1397 | (self.nanos.as_inner() / NANOS_PER_MILLI) as u64, |
1398 | self.nanos.as_inner() % NANOS_PER_MILLI, |
1399 | NANOS_PER_MILLI / 10, |
1400 | prefix, |
1401 | "ms" , |
1402 | ) |
1403 | } else if self.nanos.as_inner() >= NANOS_PER_MICRO { |
1404 | fmt_decimal( |
1405 | f, |
1406 | (self.nanos.as_inner() / NANOS_PER_MICRO) as u64, |
1407 | self.nanos.as_inner() % NANOS_PER_MICRO, |
1408 | NANOS_PER_MICRO / 10, |
1409 | prefix, |
1410 | "µs" , |
1411 | ) |
1412 | } else { |
1413 | fmt_decimal(f, self.nanos.as_inner() as u64, 0, 1, prefix, "ns" ) |
1414 | } |
1415 | } |
1416 | } |
1417 | |
1418 | /// An error which can be returned when converting a floating-point value of seconds |
1419 | /// into a [`Duration`]. |
1420 | /// |
1421 | /// This error is used as the error type for [`Duration::try_from_secs_f32`] and |
1422 | /// [`Duration::try_from_secs_f64`]. |
1423 | /// |
1424 | /// # Example |
1425 | /// |
1426 | /// ``` |
1427 | /// use std::time::Duration; |
1428 | /// |
1429 | /// if let Err(e) = Duration::try_from_secs_f32(-1.0) { |
1430 | /// println!("Failed conversion to Duration: {e}" ); |
1431 | /// } |
1432 | /// ``` |
1433 | #[derive (Debug, Clone, PartialEq, Eq)] |
1434 | #[stable (feature = "duration_checked_float" , since = "1.66.0" )] |
1435 | pub struct TryFromFloatSecsError { |
1436 | kind: TryFromFloatSecsErrorKind, |
1437 | } |
1438 | |
1439 | impl TryFromFloatSecsError { |
1440 | const fn description(&self) -> &'static str { |
1441 | match self.kind { |
1442 | TryFromFloatSecsErrorKind::Negative => { |
1443 | "cannot convert float seconds to Duration: value is negative" |
1444 | } |
1445 | TryFromFloatSecsErrorKind::OverflowOrNan => { |
1446 | "cannot convert float seconds to Duration: value is either too big or NaN" |
1447 | } |
1448 | } |
1449 | } |
1450 | } |
1451 | |
1452 | #[stable (feature = "duration_checked_float" , since = "1.66.0" )] |
1453 | impl fmt::Display for TryFromFloatSecsError { |
1454 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
1455 | self.description().fmt(f) |
1456 | } |
1457 | } |
1458 | |
1459 | #[derive (Debug, Clone, PartialEq, Eq)] |
1460 | enum TryFromFloatSecsErrorKind { |
1461 | // Value is negative. |
1462 | Negative, |
1463 | // Value is either too big to be represented as `Duration` or `NaN`. |
1464 | OverflowOrNan, |
1465 | } |
1466 | |
1467 | macro_rules! try_from_secs { |
1468 | ( |
1469 | secs = $secs: expr, |
1470 | mantissa_bits = $mant_bits: literal, |
1471 | exponent_bits = $exp_bits: literal, |
1472 | offset = $offset: literal, |
1473 | bits_ty = $bits_ty:ty, |
1474 | double_ty = $double_ty:ty, |
1475 | ) => {{ |
1476 | const MIN_EXP: i16 = 1 - (1i16 << $exp_bits) / 2; |
1477 | const MANT_MASK: $bits_ty = (1 << $mant_bits) - 1; |
1478 | const EXP_MASK: $bits_ty = (1 << $exp_bits) - 1; |
1479 | |
1480 | if $secs < 0.0 { |
1481 | return Err(TryFromFloatSecsError { kind: TryFromFloatSecsErrorKind::Negative }); |
1482 | } |
1483 | |
1484 | let bits = $secs.to_bits(); |
1485 | let mant = (bits & MANT_MASK) | (MANT_MASK + 1); |
1486 | let exp = ((bits >> $mant_bits) & EXP_MASK) as i16 + MIN_EXP; |
1487 | |
1488 | let (secs, nanos) = if exp < -31 { |
1489 | // the input represents less than 1ns and can not be rounded to it |
1490 | (0u64, 0u32) |
1491 | } else if exp < 0 { |
1492 | // the input is less than 1 second |
1493 | let t = <$double_ty>::from(mant) << ($offset + exp); |
1494 | let nanos_offset = $mant_bits + $offset; |
1495 | let nanos_tmp = u128::from(NANOS_PER_SEC) * u128::from(t); |
1496 | let nanos = (nanos_tmp >> nanos_offset) as u32; |
1497 | |
1498 | let rem_mask = (1 << nanos_offset) - 1; |
1499 | let rem_msb_mask = 1 << (nanos_offset - 1); |
1500 | let rem = nanos_tmp & rem_mask; |
1501 | let is_tie = rem == rem_msb_mask; |
1502 | let is_even = (nanos & 1) == 0; |
1503 | let rem_msb = nanos_tmp & rem_msb_mask == 0; |
1504 | let add_ns = !(rem_msb || (is_even && is_tie)); |
1505 | |
1506 | // f32 does not have enough precision to trigger the second branch |
1507 | // since it can not represent numbers between 0.999_999_940_395 and 1.0. |
1508 | let nanos = nanos + add_ns as u32; |
1509 | if ($mant_bits == 23) || (nanos != NANOS_PER_SEC) { (0, nanos) } else { (1, 0) } |
1510 | } else if exp < $mant_bits { |
1511 | let secs = u64::from(mant >> ($mant_bits - exp)); |
1512 | let t = <$double_ty>::from((mant << exp) & MANT_MASK); |
1513 | let nanos_offset = $mant_bits; |
1514 | let nanos_tmp = <$double_ty>::from(NANOS_PER_SEC) * t; |
1515 | let nanos = (nanos_tmp >> nanos_offset) as u32; |
1516 | |
1517 | let rem_mask = (1 << nanos_offset) - 1; |
1518 | let rem_msb_mask = 1 << (nanos_offset - 1); |
1519 | let rem = nanos_tmp & rem_mask; |
1520 | let is_tie = rem == rem_msb_mask; |
1521 | let is_even = (nanos & 1) == 0; |
1522 | let rem_msb = nanos_tmp & rem_msb_mask == 0; |
1523 | let add_ns = !(rem_msb || (is_even && is_tie)); |
1524 | |
1525 | // f32 does not have enough precision to trigger the second branch. |
1526 | // For example, it can not represent numbers between 1.999_999_880... |
1527 | // and 2.0. Bigger values result in even smaller precision of the |
1528 | // fractional part. |
1529 | let nanos = nanos + add_ns as u32; |
1530 | if ($mant_bits == 23) || (nanos != NANOS_PER_SEC) { |
1531 | (secs, nanos) |
1532 | } else { |
1533 | (secs + 1, 0) |
1534 | } |
1535 | } else if exp < 64 { |
1536 | // the input has no fractional part |
1537 | let secs = u64::from(mant) << (exp - $mant_bits); |
1538 | (secs, 0) |
1539 | } else { |
1540 | return Err(TryFromFloatSecsError { kind: TryFromFloatSecsErrorKind::OverflowOrNan }); |
1541 | }; |
1542 | |
1543 | Ok(Duration::new(secs, nanos)) |
1544 | }}; |
1545 | } |
1546 | |
1547 | impl Duration { |
1548 | /// The checked version of [`from_secs_f32`]. |
1549 | /// |
1550 | /// [`from_secs_f32`]: Duration::from_secs_f32 |
1551 | /// |
1552 | /// This constructor will return an `Err` if `secs` is negative, overflows `Duration` or not finite. |
1553 | /// |
1554 | /// # Examples |
1555 | /// ``` |
1556 | /// use std::time::Duration; |
1557 | /// |
1558 | /// let res = Duration::try_from_secs_f32(0.0); |
1559 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1560 | /// let res = Duration::try_from_secs_f32(1e-20); |
1561 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1562 | /// let res = Duration::try_from_secs_f32(4.2e-7); |
1563 | /// assert_eq!(res, Ok(Duration::new(0, 420))); |
1564 | /// let res = Duration::try_from_secs_f32(2.7); |
1565 | /// assert_eq!(res, Ok(Duration::new(2, 700_000_048))); |
1566 | /// let res = Duration::try_from_secs_f32(3e10); |
1567 | /// assert_eq!(res, Ok(Duration::new(30_000_001_024, 0))); |
1568 | /// // subnormal float: |
1569 | /// let res = Duration::try_from_secs_f32(f32::from_bits(1)); |
1570 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1571 | /// |
1572 | /// let res = Duration::try_from_secs_f32(-5.0); |
1573 | /// assert!(res.is_err()); |
1574 | /// let res = Duration::try_from_secs_f32(f32::NAN); |
1575 | /// assert!(res.is_err()); |
1576 | /// let res = Duration::try_from_secs_f32(2e19); |
1577 | /// assert!(res.is_err()); |
1578 | /// |
1579 | /// // the conversion uses rounding with tie resolution to even |
1580 | /// let res = Duration::try_from_secs_f32(0.999e-9); |
1581 | /// assert_eq!(res, Ok(Duration::new(0, 1))); |
1582 | /// |
1583 | /// // this float represents exactly 976562.5e-9 |
1584 | /// let val = f32::from_bits(0x3A80_0000); |
1585 | /// let res = Duration::try_from_secs_f32(val); |
1586 | /// assert_eq!(res, Ok(Duration::new(0, 976_562))); |
1587 | /// |
1588 | /// // this float represents exactly 2929687.5e-9 |
1589 | /// let val = f32::from_bits(0x3B40_0000); |
1590 | /// let res = Duration::try_from_secs_f32(val); |
1591 | /// assert_eq!(res, Ok(Duration::new(0, 2_929_688))); |
1592 | /// |
1593 | /// // this float represents exactly 1.000_976_562_5 |
1594 | /// let val = f32::from_bits(0x3F802000); |
1595 | /// let res = Duration::try_from_secs_f32(val); |
1596 | /// assert_eq!(res, Ok(Duration::new(1, 976_562))); |
1597 | /// |
1598 | /// // this float represents exactly 1.002_929_687_5 |
1599 | /// let val = f32::from_bits(0x3F806000); |
1600 | /// let res = Duration::try_from_secs_f32(val); |
1601 | /// assert_eq!(res, Ok(Duration::new(1, 2_929_688))); |
1602 | /// ``` |
1603 | #[stable (feature = "duration_checked_float" , since = "1.66.0" )] |
1604 | #[inline ] |
1605 | pub fn try_from_secs_f32(secs: f32) -> Result<Duration, TryFromFloatSecsError> { |
1606 | try_from_secs!( |
1607 | secs = secs, |
1608 | mantissa_bits = 23, |
1609 | exponent_bits = 8, |
1610 | offset = 41, |
1611 | bits_ty = u32, |
1612 | double_ty = u64, |
1613 | ) |
1614 | } |
1615 | |
1616 | /// The checked version of [`from_secs_f64`]. |
1617 | /// |
1618 | /// [`from_secs_f64`]: Duration::from_secs_f64 |
1619 | /// |
1620 | /// This constructor will return an `Err` if `secs` is negative, overflows `Duration` or not finite. |
1621 | /// |
1622 | /// # Examples |
1623 | /// ``` |
1624 | /// use std::time::Duration; |
1625 | /// |
1626 | /// let res = Duration::try_from_secs_f64(0.0); |
1627 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1628 | /// let res = Duration::try_from_secs_f64(1e-20); |
1629 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1630 | /// let res = Duration::try_from_secs_f64(4.2e-7); |
1631 | /// assert_eq!(res, Ok(Duration::new(0, 420))); |
1632 | /// let res = Duration::try_from_secs_f64(2.7); |
1633 | /// assert_eq!(res, Ok(Duration::new(2, 700_000_000))); |
1634 | /// let res = Duration::try_from_secs_f64(3e10); |
1635 | /// assert_eq!(res, Ok(Duration::new(30_000_000_000, 0))); |
1636 | /// // subnormal float |
1637 | /// let res = Duration::try_from_secs_f64(f64::from_bits(1)); |
1638 | /// assert_eq!(res, Ok(Duration::new(0, 0))); |
1639 | /// |
1640 | /// let res = Duration::try_from_secs_f64(-5.0); |
1641 | /// assert!(res.is_err()); |
1642 | /// let res = Duration::try_from_secs_f64(f64::NAN); |
1643 | /// assert!(res.is_err()); |
1644 | /// let res = Duration::try_from_secs_f64(2e19); |
1645 | /// assert!(res.is_err()); |
1646 | /// |
1647 | /// // the conversion uses rounding with tie resolution to even |
1648 | /// let res = Duration::try_from_secs_f64(0.999e-9); |
1649 | /// assert_eq!(res, Ok(Duration::new(0, 1))); |
1650 | /// let res = Duration::try_from_secs_f64(0.999_999_999_499); |
1651 | /// assert_eq!(res, Ok(Duration::new(0, 999_999_999))); |
1652 | /// let res = Duration::try_from_secs_f64(0.999_999_999_501); |
1653 | /// assert_eq!(res, Ok(Duration::new(1, 0))); |
1654 | /// let res = Duration::try_from_secs_f64(42.999_999_999_499); |
1655 | /// assert_eq!(res, Ok(Duration::new(42, 999_999_999))); |
1656 | /// let res = Duration::try_from_secs_f64(42.999_999_999_501); |
1657 | /// assert_eq!(res, Ok(Duration::new(43, 0))); |
1658 | /// |
1659 | /// // this float represents exactly 976562.5e-9 |
1660 | /// let val = f64::from_bits(0x3F50_0000_0000_0000); |
1661 | /// let res = Duration::try_from_secs_f64(val); |
1662 | /// assert_eq!(res, Ok(Duration::new(0, 976_562))); |
1663 | /// |
1664 | /// // this float represents exactly 2929687.5e-9 |
1665 | /// let val = f64::from_bits(0x3F68_0000_0000_0000); |
1666 | /// let res = Duration::try_from_secs_f64(val); |
1667 | /// assert_eq!(res, Ok(Duration::new(0, 2_929_688))); |
1668 | /// |
1669 | /// // this float represents exactly 1.000_976_562_5 |
1670 | /// let val = f64::from_bits(0x3FF0_0400_0000_0000); |
1671 | /// let res = Duration::try_from_secs_f64(val); |
1672 | /// assert_eq!(res, Ok(Duration::new(1, 976_562))); |
1673 | /// |
1674 | /// // this float represents exactly 1.002_929_687_5 |
1675 | /// let val = f64::from_bits(0x3_FF00_C000_0000_000); |
1676 | /// let res = Duration::try_from_secs_f64(val); |
1677 | /// assert_eq!(res, Ok(Duration::new(1, 2_929_688))); |
1678 | /// ``` |
1679 | #[stable (feature = "duration_checked_float" , since = "1.66.0" )] |
1680 | #[inline ] |
1681 | pub fn try_from_secs_f64(secs: f64) -> Result<Duration, TryFromFloatSecsError> { |
1682 | try_from_secs!( |
1683 | secs = secs, |
1684 | mantissa_bits = 52, |
1685 | exponent_bits = 11, |
1686 | offset = 44, |
1687 | bits_ty = u64, |
1688 | double_ty = u128, |
1689 | ) |
1690 | } |
1691 | } |
1692 | |