/rust/registry/src/index.crates.io-1949cf8c6b5b557f/time-0.3.55/src/instant.rs

Source
//! The [`Instant`] struct and its associated `impl`s.

#![expect(deprecated)]

use core::borrow::Borrow;
use core::cmp::{Ord, Ordering, PartialEq, PartialOrd};
use core::ops::{Add, AddAssign, Sub, SubAssign};
use core::time::Duration as StdDuration;
use std::time::Instant as StdInstant;

use crate::SignedDuration;

/// A measurement of a monotonically non-decreasing clock. Opaque and useful only with
/// [`SignedDuration`].
///
/// Instants are always guaranteed to be no less than any previously measured instant when created,
/// and are often useful for tasks such as measuring benchmarks or timing how long an operation
/// takes.
///
/// Note, however, that instants are not guaranteed to be **steady**. In other words, each tick of
/// the underlying clock may not be the same length (e.g. some seconds may be longer than others).
/// An instant may jump forwards or experience time dilation (slow down or speed up), but it will
/// never go backwards.
///
/// Instants are opaque types that can only be compared to one another. There is no method to get
/// "the number of seconds" from an instant. Instead, it only allows measuring the duration between
/// two instants (or comparing two instants).
///
/// This implementation allows for operations with signed [`SignedDuration`]s, but is otherwise
/// identical to [`std::time::Instant`].
#[doc(hidden)]
#[deprecated(
    since = "0.3.35",
    note = "import `std::time::Instant` and `time::ext::InstantExt` instead"
)]
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Instant(pub StdInstant);

impl Instant {
    /// Returns an `Instant` corresponding to "now".
    ///
    /// ```rust
    /// # #![expect(deprecated)]
    /// # use time::Instant;
    /// println!("{:?}", Instant::now());
    /// ```
    #[inline]
    pub fn now() -> Self {
        Self(StdInstant::now())
    }

    /// Returns the amount of time elapsed since this instant was created. The duration will always
    /// be nonnegative if the instant is not synthetically created.
    ///
    /// ```rust
    /// # #![expect(deprecated)]
    /// # use time::{Instant, ext::{NumericalStdDuration, NumericalDuration}};
    /// # use std::thread;
    /// let instant = Instant::now();
    /// thread::sleep(1.std_milliseconds());
    /// assert!(instant.elapsed() >= 1.milliseconds());
    /// ```
    #[inline]
    pub fn elapsed(self) -> SignedDuration {
        Self::now() - self
    }

    /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
    /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
    /// otherwise.
    ///
    /// ```rust
    /// # #![expect(deprecated)]
    /// # use time::{Instant, ext::NumericalDuration};
    /// let now = Instant::now();
    /// assert_eq!(now.checked_add(5.seconds()), Some(now + 5.seconds()));
    /// assert_eq!(now.checked_add((-5).seconds()), Some(now + (-5).seconds()));
    /// ```
    #[inline]
    pub fn checked_add(self, duration: SignedDuration) -> Option<Self> {
        if duration.is_zero() {
            Some(self)
        } else if duration.is_positive() {
            self.0.checked_add(duration.unsigned_abs()).map(Self)
        } else {
            debug_assert!(duration.is_negative());
            self.0.checked_sub(duration.unsigned_abs()).map(Self)
        }
    }

    /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
    /// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
    /// otherwise.
    ///
    /// ```rust
    /// # #![expect(deprecated)]
    /// # use time::{Instant, ext::NumericalDuration};
    /// let now = Instant::now();
    /// assert_eq!(now.checked_sub(5.seconds()), Some(now - 5.seconds()));
    /// assert_eq!(now.checked_sub((-5).seconds()), Some(now - (-5).seconds()));
    /// ```
    #[inline]
    pub fn checked_sub(self, duration: SignedDuration) -> Option<Self> {
        if duration.is_zero() {
            Some(self)
        } else if duration.is_positive() {
            self.0.checked_sub(duration.unsigned_abs()).map(Self)
        } else {
            debug_assert!(duration.is_negative());
            self.0.checked_add(duration.unsigned_abs()).map(Self)
        }
    }

    /// Obtain the inner [`std::time::Instant`].
    ///
    /// ```rust
    /// # #![expect(deprecated)]
    /// # use time::Instant;
    /// let now = Instant::now();
    /// assert_eq!(now.into_inner(), now.0);
    /// ```
    #[inline]
    pub const fn into_inner(self) -> StdInstant {
        self.0
    }
}

impl From<StdInstant> for Instant {
    #[inline]
    fn from(instant: StdInstant) -> Self {
        Self(instant)
    }
}

impl From<Instant> for StdInstant {
    #[inline]
    fn from(instant: Instant) -> Self {
        instant.0
    }
}

impl Sub for Instant {
    type Output = SignedDuration;

    /// # Panics
    ///
    /// This may panic if an overflow occurs.
    #[inline]
    fn sub(self, other: Self) -> Self::Output {
        match self.0.cmp(&other.0) {
            Ordering::Equal => SignedDuration::ZERO,
            Ordering::Greater => (self.0 - other.0)
                .try_into()
                .expect("overflow converting `std::time::Duration` to `time::SignedDuration`"),
            Ordering::Less => -SignedDuration::try_from(other.0 - self.0)
                .expect("overflow converting `std::time::Duration` to `time::SignedDuration`"),
        }
    }
}

impl Sub<StdInstant> for Instant {
    type Output = SignedDuration;

    #[inline]
    fn sub(self, other: StdInstant) -> Self::Output {
        self - Self(other)
    }
}

impl Sub<Instant> for StdInstant {
    type Output = SignedDuration;

    #[inline]
    fn sub(self, other: Instant) -> Self::Output {
        Instant(self) - other
    }
}

impl Add<SignedDuration> for Instant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add(self, duration: SignedDuration) -> Self::Output {
        if duration.is_positive() {
            Self(self.0 + duration.unsigned_abs())
        } else if duration.is_negative() {
            #[expect(clippy::unchecked_time_subtraction)]
            Self(self.0 - duration.unsigned_abs())
        } else {
            debug_assert!(duration.is_zero());
            self
        }
    }
}

impl Add<SignedDuration> for StdInstant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add(self, duration: SignedDuration) -> Self::Output {
        (Instant(self) + duration).0
    }
}

impl Add<StdDuration> for Instant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add(self, duration: StdDuration) -> Self::Output {
        Self(self.0 + duration)
    }
}

impl AddAssign<SignedDuration> for Instant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add_assign(&mut self, rhs: SignedDuration) {
        *self = *self + rhs;
    }
}

impl AddAssign<StdDuration> for Instant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add_assign(&mut self, rhs: StdDuration) {
        *self = *self + rhs;
    }
}

impl AddAssign<SignedDuration> for StdInstant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn add_assign(&mut self, rhs: SignedDuration) {
        *self = *self + rhs;
    }
}

impl Sub<SignedDuration> for Instant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub(self, duration: SignedDuration) -> Self::Output {
        if duration.is_positive() {
            #[expect(clippy::unchecked_time_subtraction)]
            Self(self.0 - duration.unsigned_abs())
        } else if duration.is_negative() {
            Self(self.0 + duration.unsigned_abs())
        } else {
            debug_assert!(duration.is_zero());
            self
        }
    }
}

impl Sub<SignedDuration> for StdInstant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub(self, duration: SignedDuration) -> Self::Output {
        (Instant(self) - duration).0
    }
}

impl Sub<StdDuration> for Instant {
    type Output = Self;

    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub(self, duration: StdDuration) -> Self::Output {
        #[expect(clippy::unchecked_time_subtraction)]
        Self(self.0 - duration)
    }
}

impl SubAssign<SignedDuration> for Instant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub_assign(&mut self, rhs: SignedDuration) {
        *self = *self - rhs;
    }
}

impl SubAssign<StdDuration> for Instant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub_assign(&mut self, rhs: StdDuration) {
        *self = *self - rhs;
    }
}

impl SubAssign<SignedDuration> for StdInstant {
    /// # Panics
    ///
    /// This function may panic if the resulting point in time cannot be represented by the
    /// underlying data structure.
    #[inline]
    fn sub_assign(&mut self, rhs: SignedDuration) {
        *self = *self - rhs;
    }
}

impl PartialEq<StdInstant> for Instant {
    #[inline]
    fn eq(&self, rhs: &StdInstant) -> bool {
        self.0.eq(rhs)
    }
}

impl PartialEq<Instant> for StdInstant {
    #[inline]
    fn eq(&self, rhs: &Instant) -> bool {
        self.eq(&rhs.0)
    }
}

impl PartialOrd<StdInstant> for Instant {
    #[inline]
    fn partial_cmp(&self, rhs: &StdInstant) -> Option<Ordering> {
        self.0.partial_cmp(rhs)
    }
}

impl PartialOrd<Instant> for StdInstant {
    #[inline]
    fn partial_cmp(&self, rhs: &Instant) -> Option<Ordering> {
        self.partial_cmp(&rhs.0)
    }
}

impl AsRef<StdInstant> for Instant {
    #[inline]
    fn as_ref(&self) -> &StdInstant {
        &self.0
    }
}

impl Borrow<StdInstant> for Instant {
    #[inline]
    fn borrow(&self) -> &StdInstant {
        &self.0
    }
}

Coverage Report

Created: 2026-08-13 06:47

Line	Count	Source
1		//! The [`Instant`] struct and its associated `impl`s.
2
3		#![expect(deprecated)]
4
5		use core::borrow::Borrow;
6		use core::cmp::{Ord, Ordering, PartialEq, PartialOrd};
7		use core::ops::{Add, AddAssign, Sub, SubAssign};
8		use core::time::Duration as StdDuration;
9		use std::time::Instant as StdInstant;
10
11		use crate::SignedDuration;
12
13		/// A measurement of a monotonically non-decreasing clock. Opaque and useful only with
14		/// [`SignedDuration`].
15		///
16		/// Instants are always guaranteed to be no less than any previously measured instant when created,
17		/// and are often useful for tasks such as measuring benchmarks or timing how long an operation
18		/// takes.
19		///
20		/// Note, however, that instants are not guaranteed to be steady. In other words, each tick of
21		/// the underlying clock may not be the same length (e.g. some seconds may be longer than others).
22		/// An instant may jump forwards or experience time dilation (slow down or speed up), but it will
23		/// never go backwards.
24		///
25		/// Instants are opaque types that can only be compared to one another. There is no method to get
26		/// "the number of seconds" from an instant. Instead, it only allows measuring the duration between
27		/// two instants (or comparing two instants).
28		///
29		/// This implementation allows for operations with signed [`SignedDuration`]s, but is otherwise
30		/// identical to [`std::time::Instant`].
31		#[doc(hidden)]
32		#[deprecated(
33		since = "0.3.35",
34		note = "import `std::time::Instant` and `time::ext::InstantExt` instead"
35		)]
36		#[repr(transparent)]
37		#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
38		pub struct Instant(pub StdInstant);
39
40		impl Instant {
41		/// Returns an `Instant` corresponding to "now".
42		///
43		/// ```rust
44		/// # #![expect(deprecated)]
45		/// # use time::Instant;
46		/// println!("{:?}", Instant::now());
47		/// ```
48		#[inline]
49	0	pub fn now() -> Self {
50	0	Self(StdInstant::now())
51	0	}
52
53		/// Returns the amount of time elapsed since this instant was created. The duration will always
54		/// be nonnegative if the instant is not synthetically created.
55		///
56		/// ```rust
57		/// # #![expect(deprecated)]
58		/// # use time::{Instant, ext::{NumericalStdDuration, NumericalDuration}};
59		/// # use std::thread;
60		/// let instant = Instant::now();
61		/// thread::sleep(1.std_milliseconds());
62		/// assert!(instant.elapsed() >= 1.milliseconds());
63		/// ```
64		#[inline]
65	0	pub fn elapsed(self) -> SignedDuration {
66	0	Self::now() - self
67	0	}
68
69		/// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as
70		/// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
71		/// otherwise.
72		///
73		/// ```rust
74		/// # #![expect(deprecated)]
75		/// # use time::{Instant, ext::NumericalDuration};
76		/// let now = Instant::now();
77		/// assert_eq!(now.checked_add(5.seconds()), Some(now + 5.seconds()));
78		/// assert_eq!(now.checked_add((-5).seconds()), Some(now + (-5).seconds()));
79		/// ```
80		#[inline]
81	0	pub fn checked_add(self, duration: SignedDuration) -> Option<Self> {
82	0	if duration.is_zero() {
83	0	Some(self)
84	0	} else if duration.is_positive() {
85	0	self.0.checked_add(duration.unsigned_abs()).map(Self)
86		} else {
87	0	debug_assert!(duration.is_negative());
88	0	self.0.checked_sub(duration.unsigned_abs()).map(Self)
89		}
90	0	}
91
92		/// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as
93		/// `Instant` (which means it's inside the bounds of the underlying data structure), `None`
94		/// otherwise.
95		///
96		/// ```rust
97		/// # #![expect(deprecated)]
98		/// # use time::{Instant, ext::NumericalDuration};
99		/// let now = Instant::now();
100		/// assert_eq!(now.checked_sub(5.seconds()), Some(now - 5.seconds()));
101		/// assert_eq!(now.checked_sub((-5).seconds()), Some(now - (-5).seconds()));
102		/// ```
103		#[inline]
104	0	pub fn checked_sub(self, duration: SignedDuration) -> Option<Self> {
105	0	if duration.is_zero() {
106	0	Some(self)
107	0	} else if duration.is_positive() {
108	0	self.0.checked_sub(duration.unsigned_abs()).map(Self)
109		} else {
110	0	debug_assert!(duration.is_negative());
111	0	self.0.checked_add(duration.unsigned_abs()).map(Self)
112		}
113	0	}
114
115		/// Obtain the inner [`std::time::Instant`].
116		///
117		/// ```rust
118		/// # #![expect(deprecated)]
119		/// # use time::Instant;
120		/// let now = Instant::now();
121		/// assert_eq!(now.into_inner(), now.0);
122		/// ```
123		#[inline]
124	0	pub const fn into_inner(self) -> StdInstant {
125	0	self.0
126	0	}
127		}
128
129		impl From<StdInstant> for Instant {
130		#[inline]
131	0	fn from(instant: StdInstant) -> Self {
132	0	Self(instant)
133	0	}
134		}
135
136		impl From<Instant> for StdInstant {
137		#[inline]
138	0	fn from(instant: Instant) -> Self {
139	0	instant.0
140	0	}
141		}
142
143		impl Sub for Instant {
144		type Output = SignedDuration;
145
146		/// # Panics
147		///
148		/// This may panic if an overflow occurs.
149		#[inline]
150	0	fn sub(self, other: Self) -> Self::Output {
151	0	match self.0.cmp(&other.0) {
152	0	Ordering::Equal => SignedDuration::ZERO,
153	0	Ordering::Greater => (self.0 - other.0)
154	0	.try_into()
155	0	.expect("overflow converting `std::time::Duration` to `time::SignedDuration`"),
156	0	Ordering::Less => -SignedDuration::try_from(other.0 - self.0)
157	0	.expect("overflow converting `std::time::Duration` to `time::SignedDuration`"),
158		}
159	0	}
160		}
161
162		impl Sub<StdInstant> for Instant {
163		type Output = SignedDuration;
164
165		#[inline]
166	0	fn sub(self, other: StdInstant) -> Self::Output {
167	0	self - Self(other)
168	0	}
169		}
170
171		impl Sub<Instant> for StdInstant {
172		type Output = SignedDuration;
173
174		#[inline]
175	0	fn sub(self, other: Instant) -> Self::Output {
176	0	Instant(self) - other
177	0	}
178		}
179
180		impl Add<SignedDuration> for Instant {
181		type Output = Self;
182
183		/// # Panics
184		///
185		/// This function may panic if the resulting point in time cannot be represented by the
186		/// underlying data structure.
187		#[inline]
188	0	fn add(self, duration: SignedDuration) -> Self::Output {
189	0	if duration.is_positive() {
190	0	Self(self.0 + duration.unsigned_abs())
191	0	} else if duration.is_negative() {
192		#[expect(clippy::unchecked_time_subtraction)]
193	0	Self(self.0 - duration.unsigned_abs())
194		} else {
195	0	debug_assert!(duration.is_zero());
196	0	self
197		}
198	0	}
199		}
200
201		impl Add<SignedDuration> for StdInstant {
202		type Output = Self;
203
204		/// # Panics
205		///
206		/// This function may panic if the resulting point in time cannot be represented by the
207		/// underlying data structure.
208		#[inline]
209	0	fn add(self, duration: SignedDuration) -> Self::Output {
210	0	(Instant(self) + duration).0
211	0	}
212		}
213
214		impl Add<StdDuration> for Instant {
215		type Output = Self;
216
217		/// # Panics
218		///
219		/// This function may panic if the resulting point in time cannot be represented by the
220		/// underlying data structure.
221		#[inline]
222	0	fn add(self, duration: StdDuration) -> Self::Output {
223	0	Self(self.0 + duration)
224	0	}
225		}
226
227		impl AddAssign<SignedDuration> for Instant {
228		/// # Panics
229		///
230		/// This function may panic if the resulting point in time cannot be represented by the
231		/// underlying data structure.
232		#[inline]
233	0	fn add_assign(&mut self, rhs: SignedDuration) {
234	0	self = self + rhs;
235	0	}
236		}
237
238		impl AddAssign<StdDuration> for Instant {
239		/// # Panics
240		///
241		/// This function may panic if the resulting point in time cannot be represented by the
242		/// underlying data structure.
243		#[inline]
244	0	fn add_assign(&mut self, rhs: StdDuration) {
245	0	self = self + rhs;
246	0	}
247		}
248
249		impl AddAssign<SignedDuration> for StdInstant {
250		/// # Panics
251		///
252		/// This function may panic if the resulting point in time cannot be represented by the
253		/// underlying data structure.
254		#[inline]
255	0	fn add_assign(&mut self, rhs: SignedDuration) {
256	0	self = self + rhs;
257	0	}
258		}
259
260		impl Sub<SignedDuration> for Instant {
261		type Output = Self;
262
263		/// # Panics
264		///
265		/// This function may panic if the resulting point in time cannot be represented by the
266		/// underlying data structure.
267		#[inline]
268	0	fn sub(self, duration: SignedDuration) -> Self::Output {
269	0	if duration.is_positive() {
270		#[expect(clippy::unchecked_time_subtraction)]
271	0	Self(self.0 - duration.unsigned_abs())
272	0	} else if duration.is_negative() {
273	0	Self(self.0 + duration.unsigned_abs())
274		} else {
275	0	debug_assert!(duration.is_zero());
276	0	self
277		}
278	0	}
279		}
280
281		impl Sub<SignedDuration> for StdInstant {
282		type Output = Self;
283
284		/// # Panics
285		///
286		/// This function may panic if the resulting point in time cannot be represented by the
287		/// underlying data structure.
288		#[inline]
289	0	fn sub(self, duration: SignedDuration) -> Self::Output {
290	0	(Instant(self) - duration).0
291	0	}
292		}
293
294		impl Sub<StdDuration> for Instant {
295		type Output = Self;
296
297		/// # Panics
298		///
299		/// This function may panic if the resulting point in time cannot be represented by the
300		/// underlying data structure.
301		#[inline]
302	0	fn sub(self, duration: StdDuration) -> Self::Output {
303		#[expect(clippy::unchecked_time_subtraction)]
304	0	Self(self.0 - duration)
305	0	}
306		}
307
308		impl SubAssign<SignedDuration> for Instant {
309		/// # Panics
310		///
311		/// This function may panic if the resulting point in time cannot be represented by the
312		/// underlying data structure.
313		#[inline]
314	0	fn sub_assign(&mut self, rhs: SignedDuration) {
315	0	self = self - rhs;
316	0	}
317		}
318
319		impl SubAssign<StdDuration> for Instant {
320		/// # Panics
321		///
322		/// This function may panic if the resulting point in time cannot be represented by the
323		/// underlying data structure.
324		#[inline]
325	0	fn sub_assign(&mut self, rhs: StdDuration) {
326	0	self = self - rhs;
327	0	}
328		}
329
330		impl SubAssign<SignedDuration> for StdInstant {
331		/// # Panics
332		///
333		/// This function may panic if the resulting point in time cannot be represented by the
334		/// underlying data structure.
335		#[inline]
336	0	fn sub_assign(&mut self, rhs: SignedDuration) {
337	0	self = self - rhs;
338	0	}
339		}
340
341		impl PartialEq<StdInstant> for Instant {
342		#[inline]
343	0	fn eq(&self, rhs: &StdInstant) -> bool {
344	0	self.0.eq(rhs)
345	0	}
346		}
347
348		impl PartialEq<Instant> for StdInstant {
349		#[inline]
350	0	fn eq(&self, rhs: &Instant) -> bool {
351	0	self.eq(&rhs.0)
352	0	}
353		}
354
355		impl PartialOrd<StdInstant> for Instant {
356		#[inline]
357	0	fn partial_cmp(&self, rhs: &StdInstant) -> Option<Ordering> {
358	0	self.0.partial_cmp(rhs)
359	0	}
360		}
361
362		impl PartialOrd<Instant> for StdInstant {
363		#[inline]
364	0	fn partial_cmp(&self, rhs: &Instant) -> Option<Ordering> {
365	0	self.partial_cmp(&rhs.0)
366	0	}
367		}
368
369		impl AsRef<StdInstant> for Instant {
370		#[inline]
371	0	fn as_ref(&self) -> &StdInstant {
372	0	&self.0
373	0	}
374		}
375
376		impl Borrow<StdInstant> for Instant {
377		#[inline]
378	0	fn borrow(&self) -> &StdInstant {
379	0	&self.0
380	0	}
381		}