[−][src]Trait embedded_time::duration::Duration

pub trait Duration: Sized + Copy + Display {
    type Rep: TimeInt;

    const PERIOD: Period;

    fn new(value: Self::Rep) -> Self;

    fn count(self) -> Self::Rep;

    fn from_ticks<Rep: TimeInt>(ticks: Rep, period: Period) -> Option<Self>
    where
        Self::Rep: TryFrom<Rep>,
    { ... }

    fn into_ticks<Rep>(self, period: Period) -> Option<Rep>
    where
        Self::Rep: TimeInt,
        Rep: TimeInt + TryFrom<Self::Rep>,
    { ... }

#[must_use]    fn min_value() -> Self::Rep { ... }

#[must_use]    fn max_value() -> Self::Rep { ... }
}

An unsigned duration of time

Each implementation defines a constant Period which is a fraction/ratio representing the period of the count's LSbit

Constructing a duration

assert_eq!(Milliseconds::<u32>::new(23), Milliseconds(23_u32));
assert_eq!(Milliseconds(23_u32), 23_u32.milliseconds());

Get the integer count

assert_eq!(Milliseconds(23_u32).count(), 23_u32);

Formatting

Just forwards the underlying integer to core::fmt::Display::fmt()

assert_eq!(format!("{}", Seconds(123_u32)), "123");

Getting H:M:S.MS... Components

let duration = 38_238_479_u32.microseconds();
let hours = Hours::<u32>::try_convert_from(duration).unwrap();
let minutes = Minutes::<u32>::try_convert_from(duration).unwrap() % Hours(1_u32);
let seconds = Seconds::<u32>::try_convert_from(duration).unwrap() % Minutes(1_u32);
let milliseconds = Milliseconds::<u32>::try_convert_from(duration).unwrap() % Seconds(1_u32);
// ...

Converting to core types

core::time::Duration

Examples

let core_duration = core::time::Duration::try_from(2_569_u32.milliseconds()).unwrap();
assert_eq!(2, core_duration.as_secs());
assert_eq!(569_000_000, core_duration.subsec_nanos());
let core_duration: core::time::Duration = 2_569_u32.milliseconds().try_into().unwrap();
assert_eq!(2, core_duration.as_secs());
assert_eq!(569_000_000, core_duration.subsec_nanos());

Converting from core types

core::time::Duration

Examples

let core_duration = core::time::Duration::new(5, 730023852);
assert_eq!(Milliseconds::<u32>::try_from(core_duration), Ok(5_730.milliseconds()));
let duration: Result<Milliseconds<u32>, _> = core::time::Duration::new(5, 730023852).try_into();
assert_eq!(duration, Ok(5_730.milliseconds()));

Errors

The duration doesn't fit in the type specified

assert!(Milliseconds::<u32>::try_from(core::time::Duration::from_millis((u32::MAX as u64) + 1)).is_err());

let duration: Result<Milliseconds<u32>, _> = core::time::Duration::from_millis((u32::MAX as u64) + 1).try_into();
assert!(duration.is_err());

Add/Sub

Panics

Panics if the rhs duration cannot be converted into the lhs duration type

In this example, the maximum u32 value of seconds is stored as u32 and converting that value to milliseconds (with u32 storage type) causes an overflow.

ⓘThis example panics
let _ = Milliseconds(24_u32) + Seconds(u32::MAX);

This example works just fine as the seconds value is first cast to u64, then converted to milliseconds.

let _ = Milliseconds(24_u64) + Seconds(u32::MAX);

Here, there is no units conversion to worry about, but u32::MAX + 1 cannot be cast to an u32.

ⓘThis example panics
let _ = Seconds(u32::MAX) - Seconds(u32::MAX as u64 + 1);

Examples

assert_eq!((Milliseconds(3_234_u32) - Seconds(2_u32)), Milliseconds(1_234_u32));
assert_eq!((Milliseconds(3_234_u64) - Seconds(2_u32)), Milliseconds(1_234_u64));
assert_eq!((Seconds(u32::MAX) - Milliseconds((u32::MAX as u64) + 1)),
    Seconds(4_290_672_328_u32));

Equality

assert_eq!(Seconds(123_u32), Seconds(123_u32));
assert_eq!(Seconds(123_u32), Milliseconds(123_000_u32));

assert_ne!(Seconds(123_u32), Milliseconds(123_001_u32));
assert_ne!(Milliseconds(123_001_u32), Seconds(123_u32));
assert_ne!(Milliseconds(123_001_u64), Seconds(123_u64));
assert_ne!(Seconds(123_u64), Milliseconds(123_001_u64));
assert_ne!(Seconds(123_u64), Milliseconds(123_001_u32));

Comparisons

assert!(Seconds(2_u32) < Seconds(3_u32));
assert!(Seconds(2_u32) < Milliseconds(2_001_u32));
assert!(Seconds(2_u32) == Milliseconds(2_000_u32));
assert!(Seconds(2_u32) > Milliseconds(1_999_u32));
assert!(Seconds(2_u32) < Milliseconds(2_001_u64));
assert!(Seconds(2_u64) < Milliseconds(2_001_u32));

Remainder

assert_eq!(Minutes(62_u32) % Hours(1_u32), Minutes(2_u32));

Associated Types

type Rep: TimeInt

The inner type of the Duration representing the count of the implementation unit

Loading content...

Associated Constants

const PERIOD: Period

A fraction/ratio representing the period of the count's LSbit. The precision of the Duration.

Loading content...

Required methods

fn new(value: Self::Rep) -> Self

Not generally useful or needed as the duration can be constructed like this:

Seconds(123_u32);
123_u32.seconds();

It only exists to allow Duration methods with default definitions to create a new duration

fn count(self) -> Self::Rep

Returns the integer value of the Duration

Examples

assert_eq!(Seconds(123_u32).count(), 123_u32);
Loading content...

Provided methods

fn from_ticks<Rep: TimeInt>(ticks: Rep, period: Period) -> Option<Self> where
    Self::Rep: TryFrom<Rep>, 

Constructs a Duration from a value of ticks and a period

Examples

assert_eq!(Microseconds::<u32>::from_ticks(5_u64, <Period>::new(1, 1_000)),
    Some(Microseconds(5_000_u32)));

// the conversion arithmetic will not cause overflow
assert_eq!(Milliseconds::<u32>::from_ticks((u32::MAX as u64) + 1, <Period>::new(1, 1_000_000)),
    Some(Milliseconds((((u32::MAX as u64) + 1) / 1_000) as u32)));

Errors

the conversion of periods causes an overflow:

assert_eq!(Milliseconds::<u32>::from_ticks(u32::MAX, <Period>::new(1, 1)),
    None);

the Self integer cast to that of the provided type fails

assert_eq!(Seconds::<u32>::from_ticks(u32::MAX as u64 + 1, <Period>::new(1, 1)),
    None);

Returns

None if the result of the conversion does not fit in the requested integer size

fn into_ticks<Rep>(self, period: Period) -> Option<Rep> where
    Self::Rep: TimeInt,
    Rep: TimeInt + TryFrom<Self::Rep>, 

Create an integer representation with LSbit period of that provided

Examples

assert_eq!(Microseconds(5_000_u32).into_ticks::<u32>(Period::new(1, 1_000)), Some(5_u32));

// the _into_ period can be any value
assert_eq!(Microseconds(5_000_u32).into_ticks::<u32>(Period::new(1, 200)), Some(1_u32));

// as long as the result fits in the provided integer, it will succeed
assert_eq!(Microseconds::<u32>(u32::MAX).into_ticks::<u64>(Period::new(1, 2_000_000)),
    Some((u32::MAX as u64) * 2));

Errors

the conversion of periods causes an overflow:

assert_eq!(Seconds(u32::MAX).into_ticks::<u32>(Period::new(1, 1_000)), None);

the Self integer cast to that of the provided type fails

assert_eq!(Seconds(u32::MAX as u64 + 1).into_ticks::<u32>(Period::new(1, 1)), None);

Returns

None if the result of the conversion does not fit in the requested integer size

#[must_use]fn min_value() -> Self::Rep

assert_eq!(Seconds::<u32>::min_value(), u32::MIN);

#[must_use]fn max_value() -> Self::Rep

assert_eq!(Seconds::<u32>::max_value(), u32::MAX);
Loading content...

Implementors

impl<Rep: TimeInt> Duration for Hours<Rep>[src]

type Rep = Rep

impl<Rep: TimeInt> Duration for Microseconds<Rep>[src]

type Rep = Rep

impl<Rep: TimeInt> Duration for Milliseconds<Rep>[src]

type Rep = Rep

impl<Rep: TimeInt> Duration for Minutes<Rep>[src]

type Rep = Rep

impl<Rep: TimeInt> Duration for Nanoseconds<Rep>[src]

type Rep = Rep

impl<Rep: TimeInt> Duration for Seconds<Rep>[src]

type Rep = Rep

Loading content...