qtty_core/lib.rs
1//! Core type system for strongly typed physical quantities.
2//!
3//! `qtty-core` provides a minimal, zero-cost units model:
4//!
5//! - A *unit* is a zero-sized marker type implementing [`Unit`].
6//! - A value tagged with a unit is a [`Quantity<U>`], backed by an `f64`.
7//! - Conversion is an explicit, type-checked scaling via [`Quantity::to`].
8//! - Derived units like velocity are expressed as [`Per<N, D>`] (e.g. `Meter/Second`).
9//!
10//! Most users should depend on `qtty` (the facade crate) unless they need direct access to these primitives.
11//!
12//! # What this crate solves
13//!
14//! - Compile-time separation of dimensions (length vs time vs angle, …).
15//! - Zero runtime overhead for unit tags (phantom types only).
16//! - A small vocabulary to express derived units via type aliases (`Per`, `DivDim`).
17//!
18//! # What this crate does not try to solve
19//!
20//! - Exact arithmetic (`Quantity` is `f64`).
21//! - General-purpose symbolic simplification of arbitrary unit expressions.
22//! - Automatic tracking of exponent dimensions (`m^2`, `s^-1`, …); only the expression forms represented by the
23//! provided types are modeled.
24//!
25//! # Quick start
26//!
27//! Convert between predefined units:
28//!
29//! ```rust
30//! use qtty_core::length::{Kilometers, Meter};
31//!
32//! let km = Kilometers::new(1.25);
33//! let m = km.to::<Meter>();
34//! assert!((m.value() - 1250.0).abs() < 1e-12);
35//! ```
36//!
37//! Compose derived units using `/`:
38//!
39//! ```rust
40//! use qtty_core::length::{Meter, Meters};
41//! use qtty_core::time::{Second, Seconds};
42//! use qtty_core::velocity::Velocity;
43//!
44//! let d = Meters::new(100.0);
45//! let t = Seconds::new(20.0);
46//! let v: Velocity<Meter, Second> = d / t;
47//! assert!((v.value() - 5.0).abs() < 1e-12);
48//! ```
49//!
50//! # `no_std`
51//!
52//! Disable default features to build `qtty-core` without `std`:
53//!
54//! ```toml
55//! [dependencies]
56//! qtty-core = { version = "0.1.0", default-features = false }
57//! ```
58//!
59//! When `std` is disabled, floating-point math that isn't available in `core` is provided via `libm`.
60//!
61//! # Feature flags
62//!
63//! - `std` (default): enables `std` support.
64//! - `serde`: enables `serde` support for `Quantity<U>`; serialization is the raw `f64` value only.
65//! - `pyo3`: enables PyO3 bindings for Python interop via `#[pyclass]` and `#[pymethods]`.
66//!
67//! # Panics and errors
68//!
69//! This crate does not define an error type and does not return `Result` from its core operations. Conversions and
70//! arithmetic are pure `f64` computations; they do not panic on their own, but they follow IEEE-754 behavior (NaN and
71//! infinities propagate according to the underlying operation).
72//!
73//! # SemVer and stability
74//!
75//! This crate is currently `0.x`. Expect breaking changes between minor versions until `1.0`.
76
77#![deny(missing_docs)]
78#![cfg_attr(not(feature = "std"), no_std)]
79#![forbid(unsafe_code)]
80
81#[cfg(not(feature = "std"))]
82extern crate libm;
83
84// ─────────────────────────────────────────────────────────────────────────────
85// Core modules
86// ─────────────────────────────────────────────────────────────────────────────
87
88mod dimension;
89#[cfg(feature = "diesel")]
90mod feature_diesel;
91#[cfg(feature = "pyo3")]
92mod feature_pyo3;
93#[cfg(feature = "serde")]
94mod feature_serde;
95mod macros;
96mod quantity;
97mod unit;
98
99// ─────────────────────────────────────────────────────────────────────────────
100// Public re-exports of core types
101// ─────────────────────────────────────────────────────────────────────────────
102
103pub use dimension::{Dimension, Dimensionless, DivDim};
104pub use quantity::Quantity;
105pub use unit::{Per, Simplify, Unit, Unitless};
106
107#[cfg(feature = "serde")]
108pub use feature_serde::serde_with_unit;
109
110// ─────────────────────────────────────────────────────────────────────────────
111// Predefined unit modules (grouped by dimension)
112// ─────────────────────────────────────────────────────────────────────────────
113
114/// Predefined unit modules (grouped by dimension).
115pub mod units;
116
117pub use units::angular;
118pub use units::frequency;
119pub use units::length;
120pub use units::mass;
121pub use units::power;
122pub use units::time;
123pub use units::unitless;
124pub use units::velocity;