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

pub trait Duration: Sized + Copy {
    fn to_generic<DestInt: TimeInt>(
        self, 
        scaling_factor: Fraction
    ) -> Result<Generic<DestInt>, ConversionError>
    where
        Self: FixedPoint,
        DestInt: TryFrom<Self::T>,
    { ... }

    fn to_rate<Rate: Rate>(&self) -> Result<Rate, ConversionError>
    where
        Rate: FixedPoint,
        Self: FixedPoint,
        Rate::T: TryFrom<Self::T>,
    { ... }
}

An unsigned, fixed-point duration type

Each implementation defines an integer type and a scaling factor Fraction.

Constructing a duration

let _ = <Milliseconds>::new(5);
let _ = Milliseconds(5_u32);
let _ = 5_u32.milliseconds();

Get the integer part

assert_eq!(Milliseconds(23_u32).integer(), &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

// (the default duration _integer_ type is `u32`)
let duration = 38_238_479_u32.microseconds();
let hours: Hours = duration.into();
let minutes = <Minutes>::from(duration) % Hours(1_u32);
let seconds = <Seconds>::from(duration) % Minutes(1_u32);
let milliseconds = <Milliseconds>::from(duration) % Seconds(1_u32);
// ...

Converting between Durations

Many intra-duration conversions can be done using From/Into:

let milliseconds = 23_000_u32.milliseconds();
assert_eq!(milliseconds.integer(), &23_000_u32);

let seconds: Seconds<u32> = milliseconds.into();
assert_eq!(seconds.integer(), &23_u32);

Others require the use of TryFrom/TryInto:

let seconds = 23_u32.seconds();
assert_eq!(seconds.integer(), &23_u32);

let milliseconds: Result<Milliseconds<u32>, _> = seconds.try_into();
assert_eq!(milliseconds.unwrap().integer(), &23_000_u32);

Converting between Durations

Many intra-duration conversions can be done using From/Into:

let milliseconds = 23_000_u32.milliseconds();
assert_eq!(milliseconds.integer(), &23_000_u32);

let seconds: Seconds<u32> = milliseconds.into();
assert_eq!(seconds.integer(), &23_u32);

Others require the use of TryFrom/TryInto:

let seconds = 23_u32.seconds();
assert_eq!(seconds.integer(), &23_u32);

let milliseconds: Result<Milliseconds<u32>, _> = seconds.try_into();
assert_eq!(milliseconds.unwrap().integer(), &23_000_u32);

Converting to core types

(core::time::Duration)

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

Converting from core types

(core::time::Duration)

Examples

let core_duration = core::time::Duration::new(5, 730_023_852);
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

ConversionError::ConversionFailure : The duration doesn't fit in the type specified

assert_eq!(
    Milliseconds::<u32>::try_from(
        core::time::Duration::from_millis((u32::MAX as u64) + 1)
    ),
    Err(ConversionError::ConversionFailure)
);

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

Converting from a Generic Duration

Examples

// Generic duration returned from an [`Instant`] method: `generic_duration`

let secs = Seconds::<u64>::try_from(generic_duration);
let secs: Result<Seconds<u64>, _> = generic_duration.try_into();

Errors

Failure will only occur if the provided value does not fit in the selected destination type.

ConversionError::Unspecified

assert_eq!(
    Seconds::<u32>::try_from(Generic::new(u32::MAX, Fraction::new(10,1))),
    Err(ConversionError::Unspecified)
);

ConversionError::ConversionFailure : The integer conversion to that of the destination type fails.

assert_eq!(
    Seconds::<u32>::try_from(Generic::new(u32::MAX as u64 + 1, Fraction::new(1,1))),
    Err(ConversionError::ConversionFailure)
);

Converting to a Generic Duration

let generic_duration = Generic::<u32>::from(5_u32.seconds());
let generic_duration: Generic<u32> = 5_u32.seconds().into();

Add/Sub

The result of the operation is the LHS type

Examples

assert_eq!((Milliseconds(2_001_u32) - Seconds(1_u32)),
    Milliseconds(1_001_u32));

assert_eq!((Milliseconds(1_u32) + Seconds(1_u32)),
    Milliseconds(1_001_u32));

Panics

The same reason the integer operation would panic. Namely, if the result overflows the type.

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

Comparisons

assert_eq!(Seconds(2_u32), Milliseconds(2_000_u32));
assert_ne!(Seconds(2_u32), Milliseconds(2_001_u32));

assert!(Seconds(2_u32) < Milliseconds(2_001_u32));
assert!(Seconds(2_u32) > Milliseconds(1_999_u32));

Remainder

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

Provided methods

fn to_generic<DestInt: TimeInt>(
    self,
    scaling_factor: Fraction
) -> Result<Generic<DestInt>, ConversionError> where
    Self: FixedPoint,
    DestInt: TryFrom<Self::T>, 

Construct a Generic Duration from a named Duration (eg. Milliseconds)

Examples

assert_eq!(Seconds(2_u64).to_generic(Fraction::new(1, 2_000)),
    Ok(Generic::new(4_000_u32, Fraction::new(1, 2_000))));

Errors

Failure will only occur if the provided value does not fit in the selected destination type.

ConversionError::Unspecified

assert_eq!(Seconds(u32::MAX).to_generic::<u32>(Fraction::new(1, 2)),
    Err(ConversionError::Unspecified));

ConversionError::ConversionFailure : The integer conversion to that of the destination type fails.

assert_eq!(Seconds(u32::MAX as u64 + 1).to_generic::<u32>(Fraction::new(1, 1)),
    Err(ConversionError::ConversionFailure));

fn to_rate<Rate: Rate>(&self) -> Result<Rate, ConversionError> where
    Rate: FixedPoint,
    Self: FixedPoint,
    Rate::T: TryFrom<Self::T>, 

Convert to named Rate

(the duration is equal to the reciprocal of the rate)

Examples

assert_eq!(
    Microseconds(500_u32).to_rate(),
    Ok(Kilohertz(2_u32))
);

Errors

Failure will only occur if the provided value does not fit in the selected destination type.

ConversionError::Overflow : The conversion of the scaling factor causes an overflow.

assert_eq!(
    Hours(u32::MAX).to_rate::<Megahertz<u32>>(),
    Err(ConversionError::Overflow)
);

ConversionError::DivByZero : The rate is 0, therefore the reciprocal is undefined.

assert_eq!(
    Seconds(0_u32).to_rate::<Hertz<u32>>(),
    Err(ConversionError::DivByZero)
);
Loading content...

Implementors

impl<T: TimeInt> Duration for Generic<T>[src]

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

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

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

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

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

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

Loading content...