Skip to main content

Crate qtty_core

Crate qtty_core 

Source
Expand description

Core type system for strongly typed physical quantities.

qtty-core provides a minimal, zero-cost units model:

  • A unit is a zero-sized marker type implementing Unit.
  • A value tagged with a unit is a Quantity<U>, backed by an f64.
  • Conversion is an explicit, type-checked scaling via Quantity::to.
  • Derived units like velocity are expressed as Per<N, D> (e.g. Meter/Second).

Most users should depend on qtty (the facade crate) unless they need direct access to these primitives.

§What this crate solves

  • Compile-time separation of dimensions (length vs time vs angle, …).
  • Zero runtime overhead for unit tags (phantom types only).
  • Full dimensional arithmetic: m * m → m², m / s → velocity, m² / m → m.
  • Automatic compile-time verification that multiplied/divided quantities produce the correct dimension.

§What this crate does not try to solve

  • Exact arithmetic (Quantity is f64).
  • General-purpose symbolic simplification of arbitrary unit expressions.

§Quick start

Convert between predefined units:

use qtty_core::length::{Kilometers, Meter};

let km = Kilometers::new(1.25);
let m = km.to::<Meter>();
assert!((m.value() - 1250.0).abs() < 1e-12);

Compose derived units using /:

use qtty_core::length::{Meter, Meters};
use qtty_core::time::{Second, Seconds};
use qtty_core::velocity::Velocity;

let d = Meters::new(100.0);
let t = Seconds::new(20.0);
let v: Velocity<Meter, Second> = d / t;
assert!((v.value() - 5.0).abs() < 1e-12);

§no_std

Disable default features to build qtty-core without std:

[dependencies]
qtty-core = { version = "0.1.0", default-features = false }

When std is disabled, floating-point math that isn’t available in core is provided via libm.

§Feature flags

  • std (default): enables std support.
  • cross-unit-ops (default): enables direct cross-unit comparison operators (==, <, etc.) for built-in unit catalogs.
  • serde: enables serde support for Quantity<U>; serialization is the raw f64 value only.
  • pyo3: enables PyO3 bindings for Python interop via #[pyclass] and #[pymethods].

§Panics and errors

This crate does not define an error type and does not return Result from its core operations. Conversions and arithmetic are pure f64 computations; they do not panic on their own, but they follow IEEE-754 behavior (NaN and infinities propagate according to the underlying operation).

§SemVer and stability

This crate is currently 0.x. Expect breaking changes between minor versions until 1.0.

Re-exports§

pub use scalar::Exact;
pub use scalar::IntegerScalar;
pub use scalar::Real;
pub use scalar::Scalar;
pub use scalar::Transcendental;
pub use units::angular;
pub use units::area;
pub use units::frequency;
pub use units::length;
pub use units::mass;
pub use units::power;
pub use units::time;
pub use units::unitless;
pub use units::velocity;
pub use units::volume;

Modules§

scalar
Scalar traits for quantity values.
units
Predefined unit modules (grouped by dimension).

Macros§

impl_unit_conversions
Generates all pairwise conversions and cross-unit comparisons.
impl_unit_cross_unit_ops
Generates cross-unit PartialEq and PartialOrd implementations for all pairs of units.
impl_unit_from_conversions
Generates bidirectional From trait implementations for all pairs of units within a dimension.

Structs§

Dim
A physical dimension encoded as eight typenum integer exponents.
Per
Unit representing the division of two other units.
Prod
Unit representing the product of two other units.
Quantity
A quantity with a specific unit and scalar type.
Unitless
Zero-sized marker type for dimensionless quantities.

Traits§

DimDiv
Trait for dividing two dimensions (subtracts exponents).
DimMul
Trait for multiplying two dimensions (adds exponents).
Dimension
Marker trait for dimensions.
Simplify
Trait for simplifying composite unit types.
Unit
Trait implemented by every unit type.

Type Aliases§

Acceleration
Acceleration (L¹ · T⁻²).
AmountOfSubstance
Amount of substance (N¹).
Angular
Plane angle (A¹) — treated as an independent dimension for type safety.
Area
Area (L²).
Current
Electric current (I¹).
Dimensionless
Dimensionless (all exponents zero).
DivDim
Backward-compatible alias: DivDim<N, D> resolves to <N as DimDiv<D>>::Output.
Energy
Energy (M¹ · L² · T⁻²).
Force
Force (M¹ · L¹ · T⁻²).
FrequencyDim
Frequency — angular per time (A¹ · T⁻¹).
Length
Length (L¹).
LuminousIntensity
Luminous intensity (J¹).
Mass
Mass (M¹).
MulDim
Backward-compatible alias: MulDim<A, B> resolves to <A as DimMul<B>>::Output.
Power
Power (M¹ · L² · T⁻³).
Quantity32
A quantity backed by f32.
Quantity64
A quantity backed by f64 (the default).
QuantityI8
A quantity backed by i8.
QuantityI16
A quantity backed by i16.
QuantityI32
A quantity backed by i32.
QuantityI64
A quantity backed by i64.
QuantityI128
A quantity backed by i128.
Temperature
Thermodynamic temperature (Θ¹).
Time
Time (T¹).
VelocityDim
Velocity (L¹ · T⁻¹).
Volume
Volume (L³).