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

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>,
    { ... }
}
Expand description

An unsigned, fixed-point duration type

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

Constructing a duration

use embedded_time::duration::*;

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

Get the integer part

use embedded_time::duration::*;

let millis = Milliseconds(23_u32).integer();

assert_eq!(millis, 23_u32);

Formatting

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

use embedded_time::duration::*;

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

Getting H:M:S.MS… Components

use embedded_time::duration::*;

// (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:

use embedded_time::duration::*;

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

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

Others require the use of TryFrom/TryInto:

use embedded_time::duration::*;
use std::convert::{TryInto, TryFrom};

let millis = Milliseconds::<u32>::try_from(23_u32.seconds()).unwrap();
assert_eq!(millis.integer(), 23_000_u32);

let millis: Milliseconds<u32> = 23_u32.seconds().try_into().unwrap();
assert_eq!(millis.integer(), 23_000_u32);

Converting to core types

(core::time::Duration)

Note: Due to the inner types used by core::time::Duration, a lot of code bloat occurs when it is used.

Examples

use embedded_time::duration::*;
use core::convert::TryFrom;

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);
use embedded_time::duration::*;
use core::convert::TryInto;

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)

Note: Due to the inner types used by core::time::Duration, a lot of code bloat occurs when it is used.

Examples

use embedded_time::duration::*;
use core::convert::TryFrom;

let core_duration = core::time::Duration::new(5, 730_023_852);

assert_eq!(Milliseconds::<u32>::try_from(core_duration), Ok(5_730.milliseconds()));
use embedded_time::duration::*;

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

use embedded_time::{duration::*, ConversionError};

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

use embedded_time::duration::*;

// A generic duration of 2 seconds
let generic_duration = Generic::new(2_000_u32, Fraction::new(1, 1_000));

let secs = Seconds::<u64>::try_from(generic_duration).unwrap();
assert_eq!(secs.integer(), 2_u64);

let secs: Seconds<u64> = generic_duration.try_into().unwrap();
assert_eq!(secs.integer(), 2_u64);

Errors

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

ConversionError::Unspecified

use embedded_time::{duration::*, ConversionError};

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.

use embedded_time::{duration::*, ConversionError};

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 with the same scaling factor

use embedded_time::duration::*;

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

assert_eq!(generic_duration.integer(), 5_u32);

Converting to a Generic Duration with a different scaling factor

See Duration::to_generic()

Converting to a named Rate

See Duration::to_rate()

Add/Sub

The result of the operation is the LHS type

Examples

use embedded_time::duration::*;

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

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

Panics

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

ⓘ
use embedded_time::duration::*;

let _ = Seconds(u32::MAX) + Seconds(1_u32);

Mul/Div

Durations may also be multiplied and divided by integers. The result is of the LHS type. Both panicky and checked operations are available.

Comparisons

use embedded_time::duration::*;

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

use embedded_time::duration::*;

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

Provided methods

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

Examples

use embedded_time::duration::*;

let millis = Milliseconds(20_u32);

// convert into a generic duration with a different _scaling factor_
let generic = millis.to_generic::<u32>(Fraction::new(1, 2_000)).unwrap();

assert_eq!(generic.integer(), 40_u32);

Errors

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

ConversionError::Unspecified

use embedded_time::{duration::*, ConversionError};

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.

use embedded_time::{duration::*, ConversionError};

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

Convert to named Rate

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

Examples

use embedded_time::{duration::*, rate::*};

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.

use embedded_time::{duration::*, rate::*, ConversionError};

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

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

use embedded_time::{duration::*, rate::*, ConversionError};

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

Implementors