cap_primitives/time/
instant.rs

1use crate::time::Duration;
2use std::ops::{Add, AddAssign, Sub, SubAssign};
3use std::{fmt, time};
4
5/// A measurement of a monotonically nondecreasing clock.
6///
7/// This corresponds to [`std::time::Instant`].
8///
9/// This `Instant` has no `now` or `elapsed` methods. To obtain the current
10/// time or measure the duration to the current time, first obtain a
11/// [`MonotonicClock`], and then call [`MonotonicClock::now`] or
12/// [`MonotonicClock::elapsed`] instead.
13///
14/// [`MonotonicClock`]: crate::time::MonotonicClock
15/// [`MonotonicClock::now`]: crate::time::MonotonicClock::now
16/// [`MonotonicClock::elapsed`]: crate::time::MonotonicClock::elapsed
17#[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd)]
18pub struct Instant {
19    pub(crate) std: time::Instant,
20}
21
22impl Instant {
23    /// Constructs a new instance of `Self` from the given
24    /// [`std::time::Instant`].
25    #[inline]
26    pub const fn from_std(std: time::Instant) -> Self {
27        Self { std }
28    }
29
30    /// Returns the amount of time elapsed from another instant to this one.
31    ///
32    /// This corresponds to [`std::time::Instant::duration_since`].
33    #[inline]
34    pub fn duration_since(&self, earlier: Self) -> Duration {
35        self.std.duration_since(earlier.std)
36    }
37
38    /// Returns the amount of time elapsed from another instant to this one, or
39    /// None if that instant is later than this one.
40    ///
41    /// This corresponds to [`std::time::Instant::checked_duration_since`].
42    #[inline]
43    pub fn checked_duration_since(&self, earlier: Self) -> Option<Duration> {
44        self.std.checked_duration_since(earlier.std)
45    }
46
47    /// Returns the amount of time elapsed from another instant to this one, or
48    /// zero duration if that instant is later than this one.
49    ///
50    /// This corresponds to [`std::time::Instant::saturating_duration_since`].
51    #[inline]
52    pub fn saturating_duration_since(&self, earlier: Self) -> Duration {
53        self.std.saturating_duration_since(earlier.std)
54    }
55
56    /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be
57    /// represented as `Instant` (which means it's inside the bounds of the
58    /// underlying data structure), `None` otherwise.
59    ///
60    /// This corresponds to [`std::time::Instant::checked_add`].
61    #[inline]
62    pub fn checked_add(&self, duration: Duration) -> Option<Self> {
63        self.std.checked_add(duration).map(Self::from_std)
64    }
65
66    /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be
67    /// represented as `Instant` (which means it's inside the bounds of the
68    /// underlying data structure), `None` otherwise.
69    ///
70    /// This corresponds to [`std::time::Instant::checked_sub`].
71    #[inline]
72    pub fn checked_sub(&self, duration: Duration) -> Option<Self> {
73        self.std.checked_sub(duration).map(Self::from_std)
74    }
75}
76
77impl Add<Duration> for Instant {
78    type Output = Self;
79
80    /// # Panics
81    ///
82    /// This function may panic if the resulting point in time cannot be
83    /// represented by the underlying data structure. See
84    /// [`Instant::checked_add`] for a version without panic.
85    #[inline]
86    fn add(self, other: Duration) -> Self {
87        self.checked_add(other)
88            .expect("overflow when adding duration to instant")
89    }
90}
91
92impl AddAssign<Duration> for Instant {
93    #[inline]
94    fn add_assign(&mut self, other: Duration) {
95        *self = *self + other;
96    }
97}
98
99impl Sub<Duration> for Instant {
100    type Output = Self;
101
102    #[inline]
103    fn sub(self, other: Duration) -> Self {
104        self.checked_sub(other)
105            .expect("overflow when subtracting duration from instant")
106    }
107}
108
109impl SubAssign<Duration> for Instant {
110    #[inline]
111    fn sub_assign(&mut self, other: Duration) {
112        *self = *self - other;
113    }
114}
115
116impl Sub<Instant> for Instant {
117    type Output = Duration;
118
119    #[inline]
120    fn sub(self, other: Self) -> Duration {
121        self.duration_since(other)
122    }
123}
124
125impl fmt::Debug for Instant {
126    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127        self.std.fmt(f)
128    }
129}
cap_primitives/time/instant.rs

cap_primitives/time/
instant.rs
