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.now().unwrap();

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

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

Implementations

impl<Clock: Clock> Instant<Clock>

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

Construct a new Instant from the provided Clock

pub fn duration_since<Dur: Duration>(
    &self,
    other: &Self
) -> Result<Dur, ConversionError> where
    Dur::Rep: TryFrom<Clock::Rep>, 

Returns the Duration since the given Instant

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...

}

assert_eq!(Ok(Microseconds(2_000_u64)),
    Instant::<Clock>::new(5).duration_since::<Microseconds<u64>>(&Instant::<Clock>::new(3)));

assert_eq!(Err(ConversionError::NegDuration),
    Instant::<Clock>::new(3).duration_since::<Microseconds<u64>>(&Instant::<Clock>::new(5)));

Errors

• ConversionError::NegDuration : Instant is in the future
• ConversionError::Overflow : problem coverting to the desired Duration
• ConversionError::ConversionFailure : problem coverting to the desired Duration

pub fn duration_until<Dur: Duration>(
    &self,
    other: &Self
) -> Result<Dur, ConversionError> where
    Dur::Rep: TryFrom<Clock::Rep>, 

Returns the Duration until the given Instant

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(5).duration_until::<Microseconds<u64>>(&Instant::<Clock>::new(7)),
    Ok(Microseconds(2_000_u64)));

assert_eq!(Instant::<Clock>::new(7).duration_until::<Microseconds<u64>>(&Instant::<Clock>::new(5)),
    Err(ConversionError::NegDuration));

Errors

• ConversionError::NegDuration : Instant is in the past
• ConversionError::Overflow : problem coverting to the desired Duration
• ConversionError::ConversionFailure : problem coverting to the desired Duration

pub fn duration_since_epoch<Dur: Duration>(
    &self
) -> Result<Dur, ConversionError> where
    Dur::Rep: TryFrom<Clock::Rep>,
    Clock::Rep: TryFrom<Dur::Rep>, 

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_duration<Dur: Duration>(
    self,
    duration: Dur
) -> Result<Self, ConversionError> where
    Clock::Rep: TryFrom<Dur::Rep>, 

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

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

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

Errors

ConversionError::Overflow : The duration is more than half the wrap-around period of the clock

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(0).checked_add_duration(Milliseconds(u32::MAX/2 + 1)),
    Err(ConversionError::Overflow));

pub fn checked_sub_duration<Dur: Duration>(
    self,
    duration: Dur
) -> Result<Self, ConversionError> where
    Clock::Rep: TryFrom<Dur::Rep>, 

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

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

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

Errors

ConversionError::Overflow : The duration is more than half the wrap-around period of the clock

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

assert_eq!(Instant::<Clock>::new(u32::MAX).checked_sub_duration(Milliseconds(u32::MAX/2 + 1)),
    Err(ConversionError::Overflow));

Trait Implementations

impl<Clock: Clock, Dur: Duration> Add<Dur> for Instant<Clock> where
    Clock::Rep: TryFrom<Dur::Rep>, 

Add a Duration to an Instant resulting in a later Instant

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 Rep = u32;
    const PERIOD: Period = <Period>::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 Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

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

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::Rep: 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> Ord for Instant<Clock>

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 Instances resulting in a Duration

Examples

struct Clock;
impl embedded_time::Clock for Clock {
    type Rep = u32;
    const PERIOD: Period = <Period>::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::Rep: TryFrom<Dur::Rep>, 

Subtract a Duration from an Instant resulting in an earlier Instant

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 Rep = u32;
    const PERIOD: Period = <Period>::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 Rep = u32;
    const PERIOD: Period = <Period>::new(1, 1_000);
    // ...
}

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