Skip to main content

Crate tpt_math_units_dyn

Crate tpt_math_units_dyn 

Source
Expand description

Runtime dimension-checked units for dynamic/config payloads.

tpt_math_units (a wrapper around uom) checks units at compile time, which is the right tool whenever the units are known while the code is written. It cannot help when the unit is only known at runtime — a YAML file that says speed_limit: "90 km/h", a JSON payload with {"value": 12, "unit": "kWh"}, a spreadsheet column header, a plugin that reports whatever unit its sensor uses. This crate fills that gap:

  • Dimension — the seven SI base-dimension exponents as a Copy value that multiplies, divides and compares like the quantity it describes.
  • UnitDef / UnitRegistry — a symbol table mapping unit names such as "km", "min" or "kWh" onto a dimension plus the conversion to the SI base unit, with a large built-in table and room for custom units.
  • DynQuantity — a value stored in SI base units, tagged with its dimension, whose arithmetic is dimension-checked at runtime.
  • interop — conversions to and from the compile-time quantities of tpt_math_units, so dynamic input can be validated once at the boundary and be statically typed everywhere else.

§Examples

use tpt_math_units_dyn::prelude::*;

// Values that arrived as (number, unit) pairs from a config file.
let distance = DynQuantity::parse(1.0, "km")?;
let extra = DynQuantity::parse(200.0, "m")?;

// Same dimension: addition is allowed, and unit conversion is implicit
// because everything is stored in SI base units.
let total = distance.try_add(&extra)?;
assert!((total.convert_to("km")? - 1.2).abs() < 1e-12);

// Different dimensions: multiplication composes them ...
let duration = DynQuantity::parse(30.0, "min")?;
let speed = total.try_div(&duration)?;
assert_eq!(*speed.dim(), Dimension::VELOCITY);
assert!((speed.convert_to("km/h")? - 2.4).abs() < 1e-12);

// ... but addition is rejected.
let mass = DynQuantity::parse(70.0, "kg")?;
assert!(total.try_add(&mass).is_err());

§Design notes

  • A DynQuantity always stores its magnitude in SI base units, so no conversion bookkeeping is needed during arithmetic and comparisons are exact for values that came from the same unit.
  • Add/Sub panic on a dimension mismatch (a mismatch is a bug in the same way indexing out of bounds is); use the try_* methods to get a UnitError instead. Mul/Div never mismatch — they compose dimensions.
  • Unit symbols are case sensitive, as SI requires: "m" is metre, "T" is tesla and "t" is tonne.
  • Degrees Celsius and Fahrenheit are supported through the affine offset field of UnitDef.

Re-exports§

pub use crate::dimension::BaseDimension;
pub use crate::dimension::Dimension;
pub use crate::dimension::BASE_COUNT;
pub use crate::error::Result;
pub use crate::error::UnitError;
pub use crate::quantity::DynQuantity;
pub use crate::unit::builtin_registry;
pub use crate::unit::builtin_units;
pub use crate::unit::convert;
pub use crate::unit::lookup;
pub use crate::unit::lookup_unit;
pub use crate::unit::UnitDef;
pub use crate::unit::UnitRegistry;
pub use crate::unit::BUILTIN_UNITS;

Modules§

dimension
Runtime representation of an SI dimension.
error
Errors returned by the runtime unit machinery.
interop
Bridge between the compile-time quantities of tpt_math_units (i.e. uom) and the runtime DynQuantity.
prelude
The types most users need.
quantity
A runtime, dimension-checked quantity.
solve
Units-aware solvers: ODE integration, minimisation and gradients on values that carry runtime dimensions.
unit
Unit definitions and the runtime unit registry.