Struct embedded_time::Instant

pub struct Instant<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: Clock> Instant<Clock>

pub fn new(ticks: Clock::T) -> Self

Construct a new Instant from the provided Clock

pub fn checked_duration_since(&self, other: &Self) -> Option<Generic<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: &Self) -> Option<Generic<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::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: Duration>(self, duration: Dur) -> Option<Self> where
    Dur: FixedPoint,
    Clock::T: TryFrom<Dur::T> + Div<Output = 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: Duration>(self, duration: Dur) -> Option<Self> where
    Dur: FixedPoint,
    Clock::T: TryFrom<Dur::T> + Div<Output = 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: Clock, Dur: Duration> Add<Dur> for Instant<Clock> where
    Clock::T: TryFrom<Dur::T>,
    Dur: FixedPoint, 

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: Dur) -> Self::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<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Hours<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

impl<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Minutes<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

impl<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Seconds<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

impl<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Milliseconds<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

impl<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Microseconds<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

impl<T: TimeInt, Clock: Clock> Add<Instant<Clock>> for Nanoseconds<T> where
    Clock::T: TryFrom<T>, 

type Output = Instant<Clock>

The resulting type after applying the + operator.

fn add(self, rhs: Instant<Clock>) -> Self::Output

Performs the + operation.

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

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

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

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

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

Feeds this value into the given [Hasher].

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::T: Div<Output = Clock::T>, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an [Ordering] between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

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

fn eq(&self, other: &Self) -> bool

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

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

This method tests for !=.

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

fn partial_cmp(&self, other: &Self) -> 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]fn lt(&self, other: &Rhs) -> bool

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

#[must_use]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]fn gt(&self, other: &Rhs) -> bool

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

#[must_use]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: Clock, Dur: Duration> Sub<Dur> for Instant<Clock> where
    Clock::T: TryFrom<Dur::T>,
    Dur: FixedPoint, 

type Output = Self

The resulting type after applying the - operator.

fn sub(self, rhs: Dur) -> Self::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);

impl<Clock: Clock> Sub<Instant<Clock>> for Instant<Clock>

type Output = Generic<Clock::T>

The resulting type after applying the - operator.

fn sub(self, rhs: Instant<Clock>) -> Self::Output

Subtract a two Instants resulting in a Duration

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) - Instant::<Clock>::new(5_000)).integer(), 1);

Panics

Virtually the same reason the integer operation would panic. Namely, if the result overflows the type. Specifically, if the right hand side Instant is larger than the left hand side.

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

Instant::<Clock>::new(0) - Instant::<Clock>::new(1);