[−][src]Trait embedded_time::Duration
A duration of time with signed, generic storage
Each implementation defines a constant Period which is a fraction/ratio representing the
period of the count's LSbit
Implementation Example
#[derive(Copy, Clone)] struct Milliseconds<T: TimeInt>(pub T); impl<T: TimeInt> Duration for Milliseconds<T> { type Rep = T; // set the storage type // set LSbit period to 1 millisecond const PERIOD: Period = Period::new(1, 1_000); fn new(value: Self::Rep) -> Self { Self(value) } fn count(self) -> Self::Rep { self.0 } } impl<T: TimeInt> fmt::Display for Milliseconds<T> { fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), fmt::Error> { unimplemented!() } }
Constructing a duration
assert_eq!(Milliseconds::<i32>::new(23), Milliseconds(23_i32)); assert_eq!(Milliseconds(23), 23.milliseconds());
Get the integer count
assert_eq!(Milliseconds(23).count(), 23);
Formatting
Just forwards the underlying integer to core::fmt::Display::fmt()
assert_eq!(format!("{}", Seconds(123)), "123");
Getting H:M:S.MS... Components
let duration = 38_238_479.microseconds(); let hours = Hours::<i32>::try_convert_from(duration).unwrap(); let minutes = Minutes::<i32>::try_convert_from(duration).unwrap() % Hours(1); let seconds = Seconds::<i32>::try_convert_from(duration).unwrap() % Minutes(1); let milliseconds = Milliseconds::<i32>::try_convert_from(duration).unwrap() % Seconds(1); // ...
Converting to core::time::Duration
Examples
let core_duration = core::time::Duration::try_from(2_569.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.milliseconds().try_into().unwrap(); assert_eq!(2, core_duration.as_secs()); assert_eq!(569_000_000, core_duration.subsec_nanos());
Errors
Attempting to convert from a negative duration will fail
assert!(core::time::Duration::try_from((-2_569).milliseconds()).is_err()); let core_duration: Result<core::time::Duration, _> = (-2_569).milliseconds().try_into(); assert!(core_duration.is_err());
Converting from core::time::Duration
Examples
let core_duration = core::time::Duration::new(5, 730023852); assert_eq!(Milliseconds::<i32>::try_from(core_duration), Ok(5_730.milliseconds()));
let duration: Result<Milliseconds<i32>, _> = 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::<i32>::try_from(core::time::Duration::from_millis((i32::MAX as u64) + 1)).is_err()); let duration: Result<Milliseconds<i32>, _> = core::time::Duration::from_millis((i32::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 i32 value of seconds is stored as i32 and
converting that value to milliseconds (with i32 storage type) causes an overflow.
ⓘThis example panics
let _ = Milliseconds(24) + Seconds(i32::MAX);
This example works just fine as the seconds value is first cast to i64, then
converted to milliseconds.
let _ = Milliseconds(24_i64) + Seconds(i32::MAX);
Here, there is no units conversion to worry about, but i32::MAX + 1 cannot be
cast to an i32.
ⓘThis example panics
let _ = Seconds(i32::MAX) - Seconds(i32::MAX as i64 + 1);
Examples
assert_eq!((Milliseconds(3_234) - Seconds(2)), Milliseconds(1_234)); assert_eq!((Milliseconds(3_234_i64) - Seconds(2_i32)), Milliseconds(1_234_i64)); assert_eq!((Seconds(i32::MAX) - Milliseconds((i32::MAX as i64) + 1)), Seconds(2_145_336_164_i32));
Equality
assert_eq!(Seconds(123), Seconds(123)); assert_eq!(Seconds(123), Milliseconds(123_000)); assert_ne!(Seconds(123), Milliseconds(123_001)); assert_ne!(Milliseconds(123_001), Seconds(123)); assert_ne!(Milliseconds(123_001_i64), Seconds(123_i64)); assert_ne!(Seconds(123_i64), Milliseconds(123_001_i64)); assert_ne!(Seconds(123_i64), Milliseconds(123_001_i32));
Comparisons
assert!(Seconds(2) < Seconds(3)); assert!(Seconds(2) < Milliseconds(2_001)); assert!(Seconds(2) == Milliseconds(2_000)); assert!(Seconds(2) > Milliseconds(1_999)); assert!(Seconds(2_i32) < Milliseconds(2_001_i64)); assert!(Seconds(2_i64) < Milliseconds(2_001_i32));
Remainder
assert_eq!(Minutes(62) % Hours(1), Minutes(2));
Associated Types
Loading content...Associated Constants
const PERIOD: Period
A fraction/ratio representing the period of the count's LSbit. The precision of the Duration.
Required methods
fn new(value: Self::Rep) -> Self
Not generally useful or needed as the duration can be constructed like this:
Seconds(123); 123.seconds();
It only exists to allow Duration methods with default definitions to create a new duration
fn count(self) -> Self::Rep
Provided methods
fn from_ticks<Rep>(ticks: Rep, period: Period) -> Option<Self> where
Self::Rep: TimeInt + TryFrom<Rep>,
Rep: TimeInt,
Self::Rep: TimeInt + TryFrom<Rep>,
Rep: TimeInt,
Constructs a Duration from a value of ticks and a period
Examples
assert_eq!(Microseconds::<i32>::from_ticks(5_i64, Period::new(1, 1_000)), Some(Microseconds(5_000_i32))); // the conversion arithmetic will not cause overflow assert_eq!(Milliseconds::<i32>::from_ticks((i32::MAX as i64) + 1, Period::new(1, 1_000_000)), Some(Milliseconds((((i32::MAX as i64) + 1) / 1_000) as i32)));
Errors
the conversion of periods causes an overflow:
assert_eq!(Milliseconds::<i32>::from_ticks(i32::MAX, Period::new(1, 1)), None);
the Self integer cast to that of the provided type fails
assert_eq!(Seconds::<i32>::from_ticks(i32::MAX as i64 + 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>,
Self::Rep: TimeInt,
Rep: TimeInt + TryFrom<Self::Rep>,
Create an integer representation with LSbit period of that provided
Examples
assert_eq!(Microseconds(5_000_i32).into_ticks::<i32>(Period::new(1, 1_000)), Some(5_i32)); // the _into_ period can be any value assert_eq!(Microseconds(5_000_i32).into_ticks::<i32>(Period::new(1, 200)), Some(1_i32)); // as long as the result fits in the provided integer, it will succeed assert_eq!(Microseconds::<i32>(i32::MAX).into_ticks::<i64>(Period::new(1, 2_000_000)), Some((i32::MAX as i64) * 2));
Errors
the conversion of periods causes an overflow:
assert_eq!(Seconds(i32::MAX).into_ticks::<i32>(Period::new(1, 1_000)), None);
the Self integer cast to that of the provided type fails
assert_eq!(Seconds(i32::MAX as i64 + 1).into_ticks::<i32>(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::<i32>::min_value(), i32::MIN);
#[must_use]fn max_value() -> Self::Rep
assert_eq!(Seconds::<i32>::max_value(), i32::MAX);