embedded_time::rate

Trait Rate

Source 
pub trait Rate: Sized + Copy {
    // Provided methods
    fn to_generic<DestInt>(
        self,
        scaling_factor: Fraction,
    ) -> Result<Generic<DestInt>, ConversionError>
       where Self: FixedPoint,
             DestInt: TryFrom<Self::T> + TimeInt { ... }
    fn to_duration<Duration>(&self) -> Result<Duration, ConversionError>
       where Duration: FixedPoint + Duration,
             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 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.

ConversionError::Unspecified

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

See Rate::to_generic()

§Converting to a named Duration

See Rate::to_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§

Source

fn to_generic<DestInt>( self, scaling_factor: Fraction, ) -> Result<Generic<DestInt>, ConversionError>
where Self: FixedPoint, DestInt: TryFrom<Self::T> + TimeInt,

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.

ConversionError::Unspecified


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)
);
Source

fn to_duration<Duration>(&self) -> Result<Duration, ConversionError>
where Duration: FixedPoint + Duration, 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)
);

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§