Struct Instant

pub struct Instant<Clock: Clock> { /* private fields */ }

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)

pub fn checked_add<Dur>(self, duration: Dur) -> Option<Self>

where Dur: FixedPoint + Duration, 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>(self, duration: Dur) -> Option<Self>

where Dur: FixedPoint + Duration, 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> Add<Dur> for Instant<Clock>

where Clock::T: TryFrom<Dur::T>, Dur: FixedPoint + Duration,

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);

type Output = Instant<Clock>

The resulting type after applying the + operator.

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 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 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 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 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<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<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: 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> 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, Self: Sized,

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.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

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

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Clock: Clock> PartialOrd 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));
assert!(Instant::<Clock>::new(5) <= Instant::<Clock>::new(5));

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

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

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

where Clock::T: TryFrom<Dur::T>, Dur: FixedPoint + Duration,

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);

type Output = Instant<Clock>

The resulting type after applying the - operator.

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

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);

type Output = Generic<<Clock as Clock>::T>

The resulting type after applying the - operator.

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

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