Struct rtic_monotonic::Instant

pub struct Instant<Clock> where
    Clock: Clock,  { /* fields omitted */ }

Represents an instant of time relative to a specific Clock

Example

Typically an Instant will be obtained from a Clock

let some_clock = SomeClock;
let some_instant = some_clock.try_now().unwrap();

However, an Instant can also be constructed directly. In this case the constructed Instant is 23 * SomeClock::SCALING_FACTOR seconds since the clock’s epoch

Instant::<SomeClock>::new(23);

Implementations

impl<Clock> Instant<Clock> where
    Clock: Clock, 

pub fn new(ticks: <Clock as Clock>::T) -> Instant<Clock>

Construct a new Instant from the provided Clock

pub fn checked_duration_since(
    &self,
    other: &Instant<Clock>
) -> Option<Generic<<Clock as Clock>::T>>

Returns the amount of time elapsed from another instant to this one as a duration::Generic or None if the other instant is later than this one.

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

// Given `instant1` at 3 `Clock` ticks
// Given `instant2` at 5 `Clock` ticks
let generic_duration = instant2.checked_duration_since(&instant1).unwrap();

// Convert into a _named_ `Duration`
let microseconds: Microseconds<u32> = generic_duration.try_into().unwrap();

assert_eq!(microseconds, Microseconds(2_000_u32));

pub fn checked_duration_until(
    &self,
    other: &Instant<Clock>
) -> Option<Generic<<Clock as Clock>::T>>

Returns the amount of time elapsed from self until that given instant duration::Generic or None if the other instant is later than this one.

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

// Given `instant1` at 3 `Clock` ticks
// Given `instant2` at 5 `Clock` ticks
let generic_duration = instant1.checked_duration_until(&instant2).unwrap();

// Convert into a _named_ `Duration`
let microseconds: Microseconds<u32> = generic_duration.try_into().unwrap();

assert_eq!(microseconds, Microseconds(2_000_u32));

pub fn duration_since_epoch(&self) -> Generic<<Clock as Clock>::T>

Returns the Duration (in the provided units) since the beginning of time (the Clock’s 0)

If it is a wrapping clock, the result is meaningless.

pub fn checked_add<Dur>(self, duration: Dur) -> Option<Instant<Clock>> where
    Dur: Duration + FixedPoint,
    <Clock as Clock>::T: TryFrom<<Dur as FixedPoint>::T>,
    <Clock as Clock>::T: Div<<Clock as Clock>::T>,
    <<Clock as Clock>::T as Div<<Clock as Clock>::T>>::Output == <Clock as Clock>::T, 

This Instant + Duration = later (future) Instant

Returns None if the Duration is too large

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

assert_eq!(
    Instant::<Clock>::new(0).checked_add(Milliseconds(u32::MAX/2)),
    Some(Instant::<Clock>::new(u32::MAX/2))
);

assert_eq!(
    Instant::<Clock>::new(0).checked_add(Milliseconds(u32::MAX/2 + 1)),
    None
);

pub fn checked_sub<Dur>(self, duration: Dur) -> Option<Instant<Clock>> where
    Dur: Duration + FixedPoint,
    <Clock as Clock>::T: TryFrom<<Dur as FixedPoint>::T>,
    <Clock as Clock>::T: Div<<Clock as Clock>::T>,
    <<Clock as Clock>::T as Div<<Clock as Clock>::T>>::Output == <Clock as Clock>::T, 

This Instant - Duration = earlier Instant

Returns None if the Duration is too large

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(u32::MAX).checked_sub(Milliseconds(u32::MAX/2)),
    Some(Instant::<Clock>::new(u32::MAX - u32::MAX/2)));

assert_eq!(Instant::<Clock>::new(u32::MAX).checked_sub(Milliseconds(u32::MAX/2 + 1)),
    None);

Trait Implementations

impl<Clock, Dur> Add<Dur> for Instant<Clock> where
    Clock: Clock,
    Dur: Duration + FixedPoint,
    <Clock as Clock>::T: TryFrom<<Dur as FixedPoint>::T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

pub fn add(self, rhs: Dur) -> <Instant<Clock> as Add<Dur>>::Output

Add a Duration to an Instant resulting in a new, later Instant

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(1) + Seconds(3_u32),
    Instant::<Clock>::new(3_001));
assert_eq!(Instant::<Clock>::new(1) + Milliseconds(700_u32),
    Instant::<Clock>::new(701));
assert_eq!(Instant::<Clock>::new(1) + Milliseconds(700_u64),
    Instant::<Clock>::new(701));

// maximum duration allowed
assert_eq!(Instant::<Clock>::new(0) + Milliseconds(i32::MAX as u32),
   Instant::<Clock>::new(u32::MAX/2));

Panics

Virtually the same reason the integer operation would panic. Namely, if the result overflows the type. Specifically, if the duration is more than half the wrap-around period of the clock.

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

Instant::<Clock>::new(0) + Milliseconds(u32::MAX/2 + 1);

impl<Clock> Clone for Instant<Clock> where
    Clock: Clock, 

pub fn clone(&self) -> Instant<Clock>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Clock> Copy for Instant<Clock> where
    Clock: Clock, 

impl<Clock> Debug for Instant<Clock> where
    Clock: Clock + Debug,
    <Clock as Clock>::T: Debug, 

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Clock> Eq for Instant<Clock> where
    Clock: Clock, 

impl<Clock> Hash for Instant<Clock> where
    Clock: Clock, 

pub fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<Clock> Ord for Instant<Clock> where
    Clock: Clock,
    <Clock as Clock>::T: Div<<Clock as Clock>::T>,
    <<Clock as Clock>::T as Div<<Clock as Clock>::T>>::Output == <Clock as Clock>::T, 

pub fn cmp(&self, other: &Instant<Clock>) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<Clock> PartialEq<Instant<Clock>> for Instant<Clock> where
    Clock: Clock, 

pub fn eq(&self, other: &Instant<Clock>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Clock> PartialOrd<Instant<Clock>> for Instant<Clock> where
    Clock: Clock, 

pub fn partial_cmp(&self, other: &Instant<Clock>) -> Option<Ordering>

Calculates the difference between two Instants resulting in a Duration

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

assert!(Instant::<Clock>::new(5) > Instant::<Clock>::new(3));
assert!(Instant::<Clock>::new(5) == Instant::<Clock>::new(5));
assert!(Instant::<Clock>::new(u32::MAX) < Instant::<Clock>::new(u32::MIN));

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Clock, Dur> Sub<Dur> for Instant<Clock> where
    Clock: Clock,
    Dur: Duration + FixedPoint,
    <Clock as Clock>::T: TryFrom<<Dur as FixedPoint>::T>, 

type Output = Instant<Clock>

The resulting type after applying the - operator.

pub fn sub(self, rhs: Dur) -> <Instant<Clock> as Sub<Dur>>::Output

Subtract a Duration from an Instant resulting in a new, earlier Instant

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(5_001) - Seconds(3_u32),
    Instant::<Clock>::new(2_001));
assert_eq!(Instant::<Clock>::new(800) - Milliseconds(700_u32),
    Instant::<Clock>::new(100));
assert_eq!(Instant::<Clock>::new(5_000) - Milliseconds(700_u64),
    Instant::<Clock>::new(4_300));

// maximum duration allowed
assert_eq!(Instant::<Clock>::new(u32::MAX) - Milliseconds(i32::MAX as u32),
    Instant::<Clock>::new(u32::MAX/2 + 1));

Panics

Virtually the same reason the integer operation would panic. Namely, if the result overflows the type. Specifically, if the duration is more than half the wrap-around period of the clock.

struct Clock;
impl embedded_time::Clock for Clock {
    type T = u32;
    const SCALING_FACTOR: Fraction = Fraction::new(1, 1_000);
    // ...
}

Instant::<Clock>::new(u32::MAX) - Milliseconds(u32::MAX/2 + 1);