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 Duration
s
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
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
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.
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
Converting to a named 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
fn to_generic<DestInt: TimeInt>(
self,
scaling_factor: Fraction
) -> Result<Generic<DestInt>, ConversionError> where
Self: FixedPoint,
DestInt: TryFrom<Self::T>,
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
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.
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));
fn to_rate<Rate: Rate>(&self) -> Result<Rate, ConversionError> where
Rate: FixedPoint,
Self: FixedPoint,
Rate::T: TryFrom<Self::T>,
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
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)
);