Trait embedded_time::rate::Rate [−][src]
pub trait Rate: Sized + Copy {
fn to_generic<DestInt: TimeInt>(
self,
scaling_factor: Fraction
) -> Result<Generic<DestInt>, ConversionError>
where
Self: FixedPoint,
DestInt: TryFrom<Self::T>,
{ ... }
fn to_duration<Duration: Duration>(
&self
) -> Result<Duration, ConversionError>
where
Duration: FixedPoint,
Self: FixedPoint,
Duration::T: TryFrom<Self::T>,
{ ... }
}
Expand description
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 Rate
s
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
Creating a custom Rate
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>,
fn to_generic<DestInt: TimeInt>(
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>,
fn to_duration<Duration: Duration>(&self) -> Result<Duration, ConversionError> where
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)
);