Struct DynQuantity 

#[repr(C)]
pub struct DynQuantity<V: F64RealOrComplex> {
    pub value: V,
    pub exponents: UnitExponents,
}

This type represents a physical quantity via its numerical value and a unit of measurement (field exponents). The unit of measurement is not defined via the type system, but rather via the values of the UnitExponents. This means that the unit of measurement is not fixed at compile time, but can change dynamically at runtime.

This property is very useful when e.g. parsing a user-provided string to a physical quantity. For this case, DynQuantity implements the FromStr trait. The module documentation from_str has more information regarding the available syntax.

The V generic parameter needs to implement F64RealOrComplex. Currently, implementors are f64 and Complex<f64>. It is possible to convert between those two types using the methods provided by F64RealOrComplex. In general, you likely want V to be f64 except when dealing with complex quantities such as alternating currents.

This struct can also be pretty-print the quantity it represents via its std::fmt::Display implementation:

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let quantity = DynQuantity::<f64>::from_str("9.81 m/s^2").expect("parseable");
assert_eq!(quantity.to_string(), "9.81 s^-2 m".to_string());

Conversion into uom Quantity

If the uom feature is enabled, a DynQuantity can be (fallible) converted into a Quantity via TryFrom. In combination with the aforementioned parsing capabilities, this allows fallible parsing of strings to statically-typed physical quantities.

Serialization and deserialization

If the serde feature is enabled, this struct can be serialized and deserialized. Serialization creates the “standard” serde representation one would expect from the [Serialize] macro. When deserializing however, multiple options are available:

1. Using the “standard” serialized representation of a struct. For example, the yaml representation of a DynQuantity<f64> looks like this:

---
value: 2.0
exponents:
    second: 0
    meter: 1
    kilogram: 0
    ampere: 1
    kelvin: 0
    mol: 0
    candela: 0

2. Deserializing directly from a string. This uses the std::str::FromStr implementation under the hood, see the from_str module documentation. Only available if the from_str feature is enabled.
3. Deserialize directly from a real or complex value. This option is mainly here to allow deserializing a serialized uom quantity (whose serialized representation is simply its numerical value without any units). For example, deserializing 5.0 into DynQuantity<f64> produces the same result as deserializing:

---
value: 5.0
exponents:
    second: 0
    meter: 0
    kilogram: 0
    ampere: 0
    kelvin: 0
    mol: 0
    candela: 0

The three different possibilities are realized via a crate-internal untagged enum.

Fields

value: V

The value of the physical quantity.

exponents: UnitExponents

The (SI) base units of the physical quantity, represented by their exponents.

Implementations

impl<V: F64RealOrComplex> DynQuantity<V>

pub fn new(value: V, exponents: UnitExponents) -> Self

Returns a new instance of Self.

pub fn try_add(&self, other: &Self) -> Result<Self, UnitsOfSummandsNotIdentical>

Fallible addition of self and other.

Physical quantities can only be added together if their units are identical. Hence, this function first compares the .exponents fields of self and other. If they are identical, the value fields are added up and the resulting quantity is returned. Otherwise, a UnitsOfSummandsNotIdentical error is returned.

Examples

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let curr1 = DynQuantity::<f64>::from_str("1 A").expect("valid");
let curr2 = DynQuantity::<f64>::from_str("1 V*A / V").expect("valid");
let volt1 = DynQuantity::<f64>::from_str("-5 V").expect("valid");

// The currents can be added ...
let curr_sum = curr1.try_add(&curr2).expect("can be added");
assert_eq!(curr_sum.value, 2.0);
assert_eq!(curr_sum.exponents.ampere, 1);

// ... but adding a current to a voltage fails.
assert!(volt1.try_add(&curr1).is_err());

pub fn try_add_assign( &mut self, other: &Self, ) -> Result<(), UnitsOfSummandsNotIdentical>

Like DynQuantity::try_add, but assigns the sum of self and other to self instead of returning it. If the addition fails, self is not modified.

Examples

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let mut curr1 = DynQuantity::<f64>::from_str("1 A").expect("valid");
let curr2 = DynQuantity::<f64>::from_str("1 V*A / V").expect("valid");
let mut volt1 = DynQuantity::<f64>::from_str("-5 V").expect("valid");

// curr1 gets overwritten
curr1.try_add_assign(&curr2).expect("can be added");
assert_eq!(curr1.value, 2.0);
assert_eq!(curr1.exponents.ampere, 1);

// volt1 does not get modified because the addition failed
let volt_cpy = volt1.clone();
assert!(volt1.try_add_assign(&curr1).is_err());
assert_eq!(volt1, volt_cpy);

pub fn try_sub(&self, other: &Self) -> Result<Self, UnitsOfSummandsNotIdentical>

Fallible subtraction of self and other.

Physical quantities can only be subtracted from each other if their units are identical. Hence, this function first compares the .exponents fields of self and other. If they are identical, the value fields are subtracted up and the resulting quantity is returned. Otherwise, a UnitsOfSummandsNotIdentical error is returned.

Examples

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let curr1 = DynQuantity::<f64>::from_str("1 A").expect("valid");
let curr2 = DynQuantity::<f64>::from_str("1 V*A / V").expect("valid");
let volt1 = DynQuantity::<f64>::from_str("-5 V").expect("valid");

// The currents can be subtracted ...
let curr_sum = curr1.try_sub(&curr2).expect("can be added");
assert_eq!(curr_sum.value, 0.0);
assert_eq!(curr_sum.exponents.ampere, 1);

// ... but sbutracting a current from a voltage fails.
assert!(volt1.try_sub(&curr1).is_err());

pub fn try_sub_assign( &mut self, other: &Self, ) -> Result<(), UnitsOfSummandsNotIdentical>

Like DynQuantity::try_sub, but assigns the difference of self and other to self instead of returning it. If the subtraction fails, self is not modified.

Examples

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let mut curr1 = DynQuantity::<f64>::from_str("1 A").expect("valid");
let curr2 = DynQuantity::<f64>::from_str("1 V*A / V").expect("valid");
let mut volt1 = DynQuantity::<f64>::from_str("-5 V").expect("valid");

// curr1 gets overwritten
curr1.try_sub_assign(&curr2).expect("can be added");
assert_eq!(curr1.value, 0.0);
assert_eq!(curr1.exponents.ampere, 1);

// volt1 does not get modified because the addition failed
let volt_cpy = volt1.clone();
assert!(volt1.try_sub_assign(&curr1).is_err());
assert_eq!(volt1, volt_cpy);

pub fn powi(self, n: i32) -> Self

Raises self to an integer power.

Examples

use std::str::FromStr;
use dyn_quantity::DynQuantity;

let curr = DynQuantity::<f64>::from_str("2 A^2").expect("valid");
let result = curr.powi(3);
assert_eq!(result.value, 8.0);
assert_eq!(result.exponents.ampere, 6);

pub fn try_nthroot(self, n: i32) -> Result<Self, RootError>

Tries to calculate the nth root of self.

Trait Implementations

impl<V: Clone + F64RealOrComplex> Clone for DynQuantity<V>

fn clone(&self) -> DynQuantity<V>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<V: Debug + F64RealOrComplex> Debug for DynQuantity<V>

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

Formats the value using the given formatter.

impl<V: Default + F64RealOrComplex> Default for DynQuantity<V>

fn default() -> DynQuantity<V>

Returns the “default value” for a type.

impl<V: F64RealOrComplex> Display for DynQuantity<V>

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

Formats the value using the given formatter.

impl<V: F64RealOrComplex> Div for DynQuantity<V>

type Output = DynQuantity<V>

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl<V: F64RealOrComplex> DivAssign for DynQuantity<V>

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl<V: F64RealOrComplex> Mul for DynQuantity<V>

type Output = DynQuantity<V>

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl<V: F64RealOrComplex> MulAssign for DynQuantity<V>

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl<V: PartialEq + F64RealOrComplex> PartialEq for DynQuantity<V>

fn eq(&self, other: &DynQuantity<V>) -> bool

Tests for self and other values to be equal, and is used by ==.

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 TryFrom<DynQuantity<Complex<f64>>> for DynQuantity<f64>

type Error = NotConvertibleFromComplexF64

The type returned in the event of a conversion error.

fn try_from(quantity: DynQuantity<Complex<f64>>) -> Result<Self, Self::Error>

Performs the conversion.

impl<V: F64RealOrComplex> StructuralPartialEq for DynQuantity<V>