1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

use core::fmt::Debug;
use core::time::Duration;

// TODO: this is infallible however some instants are not (`embedded_time` crate for example)
/// A trait outlining the behavior of a timekeeping type.
///
/// This trait allows `libsw` to be agnostic about timekeeping: any type which
/// implements `Instant` can be used within a
/// [`StopwatchImpl`](crate::StopwatchImpl).
///
/// # Provided implementations
///
/// `libsw` provides `Instant` implementations for a number of timekeeping
/// types.
///
/// | Type                    | Feature flag     | Notes                   |
/// |-------------------------|------------------|-------------------------|
/// | `std::time::Instant`    | `std_instant`    |                         |
/// | `std::time::SystemTime` | `std_systemtime` |                         |
/// | `tokio::time::Instant`  | `tokio`          |                         |
/// | `time::Instant`         | `time`           | Bumps MSRV to `1.62.1`. |
/// | `coarsetime::Instant`   | `coarsetime`     |                         |
///
/// If a timekeeping type you want to use isn't supported out of the box, please
/// consider [filing an
/// issue](https://gitlab.com/nissaofthesea/libsw/-/issues/new) on GitLab. If
/// you already implemented `Instant` for it, consider sending a PR upstream.
pub trait Instant: Copy + Debug + Sized {
    /// Returns the current instant in time.
    fn now() -> Self;

    /// Returns an instant ahead of `self` by the given [`Duration`] of time.
    ///
    /// Returns [`None`] if overflow occured, meaning the new instant was not
    /// representable with the underlying type.
    fn checked_add(&self, duration: Duration) -> Option<Self>;

    /// Returns an instant previous to `self` by the given [`Duration`] of time.
    ///
    /// Returns [`None`] if overflow occured, meaning the new instant was not
    /// representable with the underlying type.
    fn checked_sub(&self, duration: Duration) -> Option<Self>;

    /// Returns the [`Duration`] that has elapsed since `earlier`, returning
    /// [`Duration::ZERO`] if `earlier` is ahead of `self`.
    fn saturating_duration_since(&self, earlier: Self) -> Duration;
}