Struct embedded_time::Instant

[+] Show declaration

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

[−] Expand description

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>, [+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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>[+]

[+] Show hidden undocumented items

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, [+]

[+] Show hidden undocumented items

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>[+]

[+] Show hidden undocumented items

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>, [+]

[+] Show hidden undocumented items

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

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

[+] Expand attributes

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

Compares and returns the maximum of two values.

[+] Expand attributes

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

Compares and returns the minimum of two values.

[+] Expand attributes

#[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>[+]

[+] Show hidden undocumented items

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

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

[+] Expand attributes

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

This method tests for !=.

impl<Clock: Clock> PartialOrd<Instant<Clock>> for Instant<Clock>[+]

[+] Show hidden undocumented items

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

[+] Expand attributes

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

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

[+] Expand attributes

#[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.

[+] Expand attributes

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

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

[+] Expand attributes

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