[−][src]Trait embedded_time::rate::Rate
An unsigned, fixed-point rate type
Each implementation defines an integer type and a scaling factor Fraction.
Constructing a rate
use embedded_time::rate::*; let _ = <Kilohertz>::new(5); let _ = Kilohertz(5_u32); let _ = 5_u32.kHz();
Get the integer part
use embedded_time::rate::*; assert_eq!(Hertz(45_u32).integer(), &45_u32);
Formatting
Just forwards the underlying integer to core::fmt::Display::fmt()
use embedded_time::rate::*; assert_eq!(format!("{}", Hertz(123_u32)), "123");
Converting between Rates
Many intra-rate conversions can be done using From/Into:
use embedded_time::rate::*; let kilohertz = Kilohertz::<u32>::from(23_000_u32.Hz()); assert_eq!(kilohertz.integer(), &23_u32); let kilohertz: Kilohertz<u32> = 23_000_u32.Hz().into(); assert_eq!(kilohertz.integer(), &23_u32);
Others require the use of TryFrom/TryInto:
use embedded_time::rate::*; use std::convert::{TryInto, TryFrom}; let hertz = Hertz::<u32>::try_from(23_u32.kHz()).unwrap(); assert_eq!(hertz.integer(), &23_000_u32); let hertz: Hertz<u32> = 23_u32.kHz().try_into().unwrap(); assert_eq!(hertz.integer(), &23_000_u32);
Converting from a Generic Rate
Examples
use embedded_time::rate::*; use core::convert::{TryFrom, TryInto}; // A generic rate of 20_000 events/second let generic_rate = Generic::new(10_u32, Fraction::new(2_000, 1)); let rate = KilobitsPerSecond::<u32>::try_from(generic_rate).unwrap(); assert_eq!(rate, 20_u32.kbps()); let rate: KilobitsPerSecond<u32> = generic_rate.try_into().unwrap(); assert_eq!(rate, 20_u32.kbps());
Errors
Failure will only occur if the provided value does not fit in the selected destination type.
use embedded_time::{rate::*, ConversionError}; use core::convert::TryFrom; assert_eq!( Hertz::<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::{rate::*, ConversionError}; assert_eq!( Hertz::<u32>::try_from(Generic::new(u32::MAX as u64 + 1, Fraction::new(1,1))), Err(ConversionError::ConversionFailure) );
Converting to a Generic Rate with the same scaling factor
use embedded_time::rate::*; let generic_rate = Generic::<u32>::from(5_u32.Hz()); let generic_rate: Generic<u32> = 5_u32.Hz().into(); assert_eq!(generic_rate.integer(), &5_u32);
Converting to a Generic Rate with a different scaling factor
Converting to a named Duration
Add/Sub
The result of the operation is the LHS type
Examples
use embedded_time::rate::*; assert_eq!((Hertz(1_u32) + 1_u32.kHz()), Hertz(1_001_u32)); assert_eq!((Hertz(2_001_u32) - 1_u32.kHz()), Hertz(1_001_u32));
Panics
The same reason the integer operation would panic. Namely, if the result overflows the type.
use embedded_time::rate::*; let _ = Hertz(u32::MAX) + Hertz(1_u32);
Mul/Div
Rates 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::rate::*; assert_eq!(Kilohertz(2_u32), Hertz(2_000_u32)); assert_ne!(Kilohertz(2_u32), Hertz(2_001_u32)); assert!(Kilohertz(2_u32) < Hertz(2_001_u32)); assert!(Kilohertz(2_u32) > Hertz(1_999_u32));
Remainder
use embedded_time::rate::*; assert_eq!(Hertz(2_037_u32) % Kilohertz(1_u32), Hertz(37_u32));
Provided methods
fn to_generic<DestInt: TimeInt>(
self,
scaling_factor: Fraction
) -> Result<Generic<DestInt>, ConversionError> where
Self: FixedPoint,
DestInt: TryFrom<Self::T>,
self,
scaling_factor: Fraction
) -> Result<Generic<DestInt>, ConversionError> where
Self: FixedPoint,
DestInt: TryFrom<Self::T>,
Construct a Generic Rate from a named Rate (eg. Kilohertz)
Examples
use embedded_time::rate::*; let kilobits = KilobitsPerSecond(20_u32); // convert into a generic rate with a different _scaling factor_ let generic = kilobits.to_generic::<u32>(Fraction::new(500, 1)).unwrap(); assert_eq!(generic.integer(), &40_u32);
Errors
Failure will only occur if the provided value does not fit in the selected destination type.
assert_eq!( Hertz(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::{fraction::Fraction, rate::*, ConversionError}; assert_eq!( Hertz(u32::MAX as u64 + 1).to_generic::<u32>(Fraction::new(1, 1)), Err(ConversionError::ConversionFailure) );
fn to_duration<Duration: Duration>(&self) -> Result<Duration, ConversionError> where
Duration: FixedPoint,
Self: FixedPoint,
Duration::T: TryFrom<Self::T>,
Duration: FixedPoint,
Self: FixedPoint,
Duration::T: TryFrom<Self::T>,
Convert to named Duration
(the rate is equal to the reciprocal of the duration)
Examples
use embedded_time::{duration::*, rate::*}; assert_eq!( Kilohertz(500_u32).to_duration(), Ok(Microseconds(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!( Megahertz(u32::MAX).to_duration::<Hours<u32>>(), Err(ConversionError::Overflow) );
ConversionError::DivByZero : The rate is 0, therefore the reciprocal is undefined.
use embedded_time::{duration::*, rate::*, ConversionError}; assert_eq!( Hertz(0_u32).to_duration::<Seconds<u32>>(), Err(ConversionError::DivByZero) );