Struct EngineeringQuantity

pub struct EngineeringQuantity<T: EQSupported<T>> { /* private fields */ }

A helper type for expressing numbers in engineering notation.

These numbers may be converted to and from integers, strings, and num_rational::Ratio. They may also be converted to floats.

Type parameter

The type parameter T is the underlying storage type used for the significand of the number. That is to say, an EngineeringQuantity<u32> uses a u32 to store the numeric part.

Implementations

impl<T: EQSupported<T>> EngineeringQuantity<T>

pub fn with_precision( &self, max_significant_figures: usize, ) -> DisplayAdapter<T>

Creates a standard DisplayAdapter for this object, with the given precision.

use engineering_repr::EngineeringQuantity as EQ;
let ee = EQ::<i32>::from(1234567);
assert_eq!(ee.with_precision(2).to_string(), "1.2M");

pub fn rkm_with_precision( &self, max_significant_figures: usize, ) -> DisplayAdapter<T>

Creates an RKM DisplayAdapter for this object in RKM mode, with the given precision.

use engineering_repr::EngineeringQuantity as EQ;
let ee = EQ::<i32>::from(1234567);
assert_eq!(ee.rkm_with_precision(2).to_string(), "1M2");

pub fn with_strict_precision( &self, max_significant_figures: usize, ) -> DisplayAdapter<T>

Creates a DisplayAdapter for this object, with strict precision. The requested digits will always be output, even trailing zeroes.

use engineering_repr::EngineeringQuantity as EQ;
let ee = EQ::<i32>::from(1_200);
assert_eq!(ee.with_strict_precision(3).to_string(), "1.20k");

impl<T: EQSupported<T>> EngineeringQuantity<T>

pub fn from_raw(significand: T, exponent: i8) -> Result<Self, Error>

Raw constructor from component parts

Construction fails if the number would overflow the storage type T.

pub fn to_raw(self) -> (T, i8)

Raw accessor to retrieve the component parts

impl<T: EQSupported<T>> EngineeringQuantity<T>

pub fn convert<U: EQSupported<U> + From<T>>(&self) -> EngineeringQuantity<U>

Conversion to a different storage type. If you can convert from type A to type B, then you can convert from EngineeringQuantity<A> to EngineeringQuantity<B>.

use engineering_repr::EngineeringQuantity as EQ;
let q = EQ::from_raw(42u32, 0).unwrap();
let q2 = q.convert::<u64>();
assert_eq!(q2.to_raw(), (42u64, 0));

pub fn try_convert<U: EQSupported<U> + TryFrom<T>>( &self, ) -> Result<EngineeringQuantity<U>, Error>

Fallible conversion to a different storage type.

Conversion fails if the number cannot be represented in the the destination storage type.

type EQ = engineering_repr::EngineeringQuantity<u32>;
let million = EQ::from_raw(1, 2).unwrap();
let r1 = million.try_convert::<u32>().unwrap();
let r2 = million.try_convert::<u16>().expect_err("overflow"); // Overflow, because 1_000_000 won't fit into a u16

pub fn normalise(self) -> Self

Scales the number to remove any unnecessary groups of trailing zeroes.

Trait Implementations

impl<T: Clone + EQSupported<T>> Clone for EngineeringQuantity<T>

fn clone(&self) -> EngineeringQuantity<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + EQSupported<T>> Debug for EngineeringQuantity<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default + EQSupported<T>> Default for EngineeringQuantity<T>

fn default() -> EngineeringQuantity<T>

Returns the “default value” for a type.

impl<'de, T: EQSupported<T> + FromStr + TryFrom<u128> + TryFrom<i128>> Deserialize<'de> for EngineeringQuantity<T>

Available on feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: EQSupported<T>> Display for EngineeringQuantity<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Default behaviour is to output to 3 significant figures, skip unnecessary trailing zeros, standard (not RKM) mode. See EngineeringQuantity::default().

Examples

use engineering_repr::EngineeringQuantity as EQ;
let ee1 = EQ::<i32>::from(1200);
assert_eq!(ee1.to_string(), "1.2k");
let ee2 = EQ::<i32>::from(123456);
assert_eq!(ee2.to_string(), "123k");

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for i128

where i128: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for i16

where i16: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for i32

where i32: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for i64

where i64: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for isize

where isize: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for u128

where u128: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for u16

where u16: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for u32

where u32: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for u64

where u64: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>> From<EngineeringQuantity<T>> for usize

where usize: From<T>,

fn from(eq: EngineeringQuantity<T>) -> Self

Conversion to the same storage type (or a larger type) is infallible due to the checks at construction time.

This is a lossy conversion, any fractional part will be truncated.

Note that if you have num_traits in scope, you may need to rephrase the conversion as TryInto::<T>::try_into().

impl<T: EQSupported<T>, U> From<T> for EngineeringQuantity<U>

where U: From<T> + EQSupported<U>,

fn from(value: T) -> Self

Integers can always be promoted on conversion to EngineeringQuantity. (For demotions, you have to convert the primitive yourself and handle any failures.)

let i = 42u32;
let _e = engineering_repr::EngineeringQuantity::<u64>::from(i);

impl<T: EQSupported<T> + FromStr> FromStr for EngineeringQuantity<T>

fn from_str(s: &str) -> Result<Self, Self::Err>

Example

use engineering_repr::EngineeringQuantity as EQ;
use std::str::FromStr as _;
let eq = EQ::<i64>::from_str("1.5k").unwrap();
assert_eq!(i64::try_from(eq).unwrap(), 1500);
// RKM style strings
let eq2 = EQ::<i64>::from_str("1k5").unwrap();
assert_eq!(eq, eq2);

type Err = Error

The associated error which can be returned from parsing.

impl<T: EQSupported<T> + From<EngineeringQuantity<T>>> Ord for EngineeringQuantity<T>

fn cmp(&self, other: &Self) -> Ordering

use engineering_repr::EngineeringQuantity as EQ;
use assertables::assert_lt;
let q2 = EQ::from_raw(41999,0).unwrap();
let q3 = EQ::from_raw(42,1).unwrap();
let q4 = EQ::from_raw(42001,0).unwrap();
assert_lt!(q2, q3);
assert_lt!(q3, q4);

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: EQSupported<T> + From<EngineeringQuantity<T>>> PartialEq for EngineeringQuantity<T>

fn eq(&self, other: &Self) -> bool

use engineering_repr::EngineeringQuantity as EQ;
let q1 = EQ::from_raw(42u32,0);
let q2 = EQ::from_raw(42u32,0);
assert_eq!(q1, q2);
let q3 = EQ::from_raw(42,1);
let q4 = EQ::from_raw(42000,0);
assert_eq!(q3, q4);

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: EQSupported<T> + From<EngineeringQuantity<T>>> PartialOrd for EngineeringQuantity<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: EQSupported<T>> Serialize for EngineeringQuantity<T>

Available on feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: EQSupported<T>> ToPrimitive for EngineeringQuantity<T>

where f64: TryFrom<EngineeringQuantity<T>>,

fn to_i64(&self) -> Option<i64>

Converts self to an i64. If the value cannot be represented by an i64, then None is returned.

use num_traits::cast::ToPrimitive as _;
let e = engineering_repr::EngineeringQuantity::<u32>::from(65_537u32);
assert_eq!(e.to_u128(), Some(65_537));
assert_eq!(e.to_u64(), Some(65_537));
assert_eq!(e.to_u16(), None); // overflow
assert_eq!(e.to_i128(), Some(65_537));
assert_eq!(e.to_i64(), Some(65_537));
assert_eq!(e.to_i16(), None); // overflow

fn to_i128(&self) -> Option<i128>

Converts self to an i128. If the value cannot be represented by an i128, then None is returned.

fn to_u128(&self) -> Option<u128>

Converts self to a u128. If the value cannot be represented by a u128, then None is returned.

fn to_f64(&self) -> Option<f64>

Converts self to an f64. If the value cannot be represented by an f64, then None is returned.

As ever, if you need to compare floating point numbers, beware of epsilon issues. If a precise comparison is needed then converting to a num_rational::Ratio may suit.

use engineering_repr::EngineeringQuantity as EQ;
use std::str::FromStr as _;
let eq = EQ::<u32>::from_str("123m").unwrap();

// TryFrom conversion
assert_eq!(f64::try_from(eq), Ok(0.123));

// Conversion via ToPrimitive
use num_traits::cast::ToPrimitive as _;
assert_eq!(eq.to_f32(), Some(0.123));
assert_eq!(eq.to_f64(), Some(0.123));

fn to_u64(&self) -> Option<u64>

Converts the value of self to a u64. If the value cannot be represented by a u64, then None is returned.

fn to_isize(&self) -> Option<isize>

Converts the value of self to an isize. If the value cannot be represented by an isize, then None is returned.

fn to_i8(&self) -> Option<i8>

Converts the value of self to an i8. If the value cannot be represented by an i8, then None is returned.

fn to_i16(&self) -> Option<i16>

Converts the value of self to an i16. If the value cannot be represented by an i16, then None is returned.

fn to_i32(&self) -> Option<i32>

Converts the value of self to an i32. If the value cannot be represented by an i32, then None is returned.

fn to_usize(&self) -> Option<usize>

Converts the value of self to a usize. If the value cannot be represented by a usize, then None is returned.

fn to_u8(&self) -> Option<u8>

Converts the value of self to a u8. If the value cannot be represented by a u8, then None is returned.

fn to_u16(&self) -> Option<u16>

Converts the value of self to a u16. If the value cannot be represented by a u16, then None is returned.

fn to_u32(&self) -> Option<u32>

Converts the value of self to a u32. If the value cannot be represented by a u32, then None is returned.

fn to_f32(&self) -> Option<f32>

Converts the value of self to an f32. Overflows may map to positive or negative inifinity, otherwise None is returned if the value cannot be represented by an f32.

impl<T: EQSupported<T> + Integer + From<EngineeringQuantity<T>>> TryFrom<EngineeringQuantity<T>> for Ratio<T>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: EngineeringQuantity<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<T: EQSupported<T>> TryFrom<EngineeringQuantity<T>> for f64

where Ratio<T>: ToPrimitive + TryFrom<EngineeringQuantity<T>, Error = Error>,

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: EngineeringQuantity<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<Ratio<T>> for EngineeringQuantity<T>

where T: Integer + EQSupported<T>,

fn try_from(value: Ratio<T>) -> Result<Self, Self::Error>

This is a precise conversion, which only succeeds if the denominator of the input Ratio is a power of 1000.

type Error = Error

The type returned in the event of a conversion error.

impl<T: Copy + EQSupported<T>> Copy for EngineeringQuantity<T>

impl<T: EQSupported<T> + From<EngineeringQuantity<T>>> Eq for EngineeringQuantity<T>