siderust-js 0.1.0

package/qtty-js/qtty/qtty-core/src/units/mass.rs

@@ -0,0 +1,488 @@
+//! Mass units.
+//!
+//! The canonical scaling unit for this dimension is [`Gram`] (`Gram::RATIO == 1.0`).
+//!
+//! This module aims for practical completeness while avoiding avoidable precision loss:
+//! - **SI grams**: full prefix ladder (yocto … yotta).
+//! - **Defined non-SI**: tonne, avoirdupois units, carat, grain.
+//! - **Science/astro**: atomic mass unit (u/Da), nominal solar mass.
+//!
+//! ```rust
+//! use qtty_core::mass::{Kilograms, SolarMass};
+//!
+//! let m = Kilograms::new(1.0);
+//! let sm = m.to::<SolarMass>();
+//! assert!(sm.value() < 1.0);
+//! ```
+//!
+//! ## All mass units
+//!
+//! ```rust
+//! use qtty_core::mass::*;
+//!
+//! macro_rules! touch {
+//!     ($T:ty, $v:expr) => {{ let q = <$T>::new($v); let _c = q; assert!(q == q); }};
+//! }
+//!
+//! touch!(Grams, 1.0);     touch!(Tonnes, 1.0);   touch!(Carats, 1.0);
+//! touch!(Grains, 1.0);    touch!(Pounds, 1.0);   touch!(Ounces, 1.0);
+//! touch!(Stones, 1.0);    touch!(ShortTons, 1.0); touch!(LongTons, 1.0);
+//! touch!(AtomicMassUnits, 1.0); touch!(SolarMasses, 1.0);
+//! ```
+
+use crate::{Quantity, Unit};
+use qtty_derive::Unit;
+
+/// Re-export from the dimension module.
+pub use crate::dimension::Mass;
+
+/// Marker trait for any [`Unit`] whose dimension is [`Mass`].
+pub trait MassUnit: Unit<Dim = Mass> {}
+impl<T: Unit<Dim = Mass>> MassUnit for T {}
+
+/// Gram.
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "g", dimension = Mass, ratio = 1.0)]
+pub struct Gram;
+/// A quantity measured in grams.
+pub type Grams = Quantity<Gram>;
+/// One gram.
+pub const G: Grams = Grams::new(1.0);
+
+/// Helper macro to declare a gram-based SI mass unit.
+///
+/// Each invocation of this macro defines, for a given prefix on grams:
+/// - a unit struct `$name` (e.g. `Kilogram`),
+/// - a shorthand type alias `$alias` (e.g. `Kg`),
+/// - a quantity type `$qty` (e.g. `Kilograms`), and
+/// - a constant `$one` equal to `1.0` of that quantity.
+///
+/// The `$ratio` argument is the conversion factor to grams, i.e.
+/// `$name::RATIO` such that `1 $sym = $ratio g`.
+macro_rules! si_gram {
+    ($name:ident, $sym:literal, $ratio:expr, $alias:ident, $qty:ident, $one:ident) => {
+        #[doc = concat!("SI mass unit `", stringify!($name), "` with gram-based prefix (symbol `", $sym,"`).")]
+        #[doc = concat!("By definition, `1 ", $sym, " = ", stringify!($ratio), " g`.")]
+        #[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+        #[unit(symbol = $sym, dimension = Mass, ratio = $ratio)]
+        pub struct $name;
+
+        #[doc = concat!("Shorthand alias for [`", stringify!($name), "`]." )]
+        pub type $alias = $name;
+
+        #[doc = concat!("Quantity measured in ", stringify!($name), " (",$sym,").")]
+        pub type $qty = Quantity<$alias>;
+
+        #[doc = concat!("Constant equal to one ", stringify!($name), " (1 ",$sym,").")]
+        pub const $one: $qty = $qty::new(1.0);
+    };
+}
+
+// Full SI prefix ladder (gram-based)
+si_gram!(Yoctogram, "yg", 1e-24, Yg, Yoctograms, YG);
+si_gram!(Zeptogram, "zg", 1e-21, Zg, Zeptograms, ZG);
+si_gram!(Attogram, "ag", 1e-18, Ag, Attograms, AG);
+si_gram!(Femtogram, "fg", 1e-15, Fg, Femtograms, FG);
+si_gram!(Picogram, "pg", 1e-12, Pg, Picograms, PG);
+si_gram!(Nanogram, "ng", 1e-9, Ng, Nanograms, NG);
+si_gram!(Microgram, "µg", 1e-6, Ug, Micrograms, UG);
+si_gram!(Milligram, "mg", 1e-3, Mg, Milligrams, MG);
+si_gram!(Centigram, "cg", 1e-2, Cg, Centigrams, CG);
+si_gram!(Decigram, "dg", 1e-1, Dg, Decigrams, DG);
+
+si_gram!(Decagram, "dag", 1e1, Dag, Decagrams, DAG);
+si_gram!(Hectogram, "hg", 1e2, Hg, Hectograms, HG);
+si_gram!(Kilogram, "kg", 1e3, Kg, Kilograms, KG);
+si_gram!(Megagram, "Mg", 1e6, MgG, Megagrams, MEGAGRAM);
+si_gram!(Gigagram, "Gg", 1e9, Gg, Gigagrams, GG);
+si_gram!(Teragram, "Tg", 1e12, Tg, Teragrams, TG);
+si_gram!(Petagram, "Pg", 1e15, PgG, Petagrams, PETAGRAM);
+si_gram!(Exagram, "Eg", 1e18, Eg, Exagrams, EG);
+si_gram!(Zettagram, "Zg", 1e21, ZgG, Zettagrams, ZETTAGRAM);
+si_gram!(Yottagram, "Yg", 1e24, YgG, Yottagrams, YOTTAGRAM);
+
+/// Tonne (metric ton): `1 t = 1_000_000 g` (exact).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "t", dimension = Mass, ratio = 1_000_000.0)]
+pub struct Tonne;
+/// Shorthand type alias for [`Tonne`].
+pub type T = Tonne;
+/// Quantity measured in tonnes.
+pub type Tonnes = Quantity<T>;
+/// One metric tonne.
+pub const TONE: Tonnes = Tonnes::new(1.0);
+
+/// Carat: `1 ct = 0.2 g` (exact).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "ct", dimension = Mass, ratio = 1.0 / 5.0)]
+pub struct Carat;
+/// Shorthand type alias for [`Carat`].
+pub type Ct = Carat;
+/// Quantity measured in carats.
+pub type Carats = Quantity<Ct>;
+/// One carat.
+pub const CT: Carats = Carats::new(1.0);
+
+/// Grain: `1 gr = 64.79891 mg` (exact) == `0.064_798_91 g`.
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "gr", dimension = Mass, ratio = 6_479_891.0 / 1_000_000_000.0)]
+pub struct Grain;
+/// Shorthand type alias for [`Grain`].
+pub type Gr = Grain;
+/// Quantity measured in grains.
+pub type Grains = Quantity<Gr>;
+/// One grain.
+pub const GR: Grains = Grains::new(1.0);
+
+/// Avoirdupois pound: `1 lb = 0.45359237 kg` (exact) == `453.59237 g`.
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "lb", dimension = Mass, ratio = 45_359_237.0 / 100_000.0)]
+pub struct Pound;
+/// Shorthand type alias for [`Pound`].
+pub type Lb = Pound;
+/// Quantity measured in pounds.
+pub type Pounds = Quantity<Lb>;
+/// One pound.
+pub const LB: Pounds = Pounds::new(1.0);
+
+/// Avoirdupois ounce: `1 oz = 1/16 lb` (exact).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "oz", dimension = Mass, ratio = (45_359_237.0 / 100_000.0) / 16.0)]
+pub struct Ounce;
+/// Shorthand type alias for [`Ounce`].
+pub type Oz = Ounce;
+/// Quantity measured in ounces.
+pub type Ounces = Quantity<Oz>;
+/// One ounce.
+pub const OZ: Ounces = Ounces::new(1.0);
+
+/// Avoirdupois stone: `1 st = 14 lb` (exact).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "st", dimension = Mass, ratio = (45_359_237.0 / 100_000.0) * 14.0)]
+pub struct Stone;
+/// Shorthand type alias for [`Stone`].
+pub type St = Stone;
+/// Quantity measured in stones.
+pub type Stones = Quantity<St>;
+/// One stone.
+pub const ST: Stones = Stones::new(1.0);
+
+/// Short ton (US customary): `2000 lb` (exact given lb).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "ton_us", dimension = Mass, ratio = (45_359_237.0 / 100_000.0) * 2000.0)]
+pub struct ShortTon;
+/// Quantity measured in short tons (US).
+pub type ShortTons = Quantity<ShortTon>;
+/// One short ton (US).
+pub const TON_US: ShortTons = ShortTons::new(1.0);
+
+/// Long ton (Imperial): `2240 lb` (exact given lb).
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "ton_uk", dimension = Mass, ratio = (45_359_237.0 / 100_000.0) * 2240.0)]
+pub struct LongTon;
+/// Quantity measured in long tons (UK).
+pub type LongTons = Quantity<LongTon>;
+/// One long ton (UK).
+pub const TON_UK: LongTons = LongTons::new(1.0);
+
+/// Unified atomic mass unit (u), a.k.a. dalton (Da).
+///
+/// Stored in grams using the CODATA recommended value for `m_u` in kilograms, converted by `1 kg = 1000 g`.
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "u", dimension = Mass, ratio = 1.660_539_068_92e-24)]
+pub struct AtomicMassUnit;
+/// Type alias shorthand for [`AtomicMassUnit`].
+pub type Dalton = AtomicMassUnit;
+/// Quantity measured in atomic mass units.
+pub type AtomicMassUnits = Quantity<AtomicMassUnit>;
+/// One atomic mass unit.
+pub const U: AtomicMassUnits = AtomicMassUnits::new(1.0);
+
+/// Nominal solar mass (IAU 2015 Resolution B3; grams per M☉).
+///
+/// This is a **conversion constant** (nominal), not a “best estimate” of the Sun’s true mass.
+#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, Unit)]
+#[unit(symbol = "M☉", dimension = Mass, ratio = 1.988_416e33)]
+pub struct SolarMass;
+/// A quantity measured in solar masses.
+pub type SolarMasses = Quantity<SolarMass>;
+/// One nominal solar mass.
+pub const MSUN: SolarMasses = SolarMasses::new(1.0);
+
+// Generate all bidirectional From implementations between mass units.
+crate::impl_unit_from_conversions!(
+    Gram,
+    Yoctogram,
+    Zeptogram,
+    Attogram,
+    Femtogram,
+    Picogram,
+    Nanogram,
+    Microgram,
+    Milligram,
+    Centigram,
+    Decigram,
+    Decagram,
+    Hectogram,
+    Kilogram,
+    Megagram,
+    Gigagram,
+    Teragram,
+    Petagram,
+    Exagram,
+    Zettagram,
+    Yottagram,
+    Tonne,
+    Carat,
+    Grain,
+    Pound,
+    Ounce,
+    Stone,
+    ShortTon,
+    LongTon,
+    AtomicMassUnit,
+    SolarMass
+);
+
+// Optional cross-unit operator support (`==`, `<`, etc.).
+#[cfg(feature = "cross-unit-ops")]
+crate::impl_unit_cross_unit_ops!(
+    Gram,
+    Yoctogram,
+    Zeptogram,
+    Attogram,
+    Femtogram,
+    Picogram,
+    Nanogram,
+    Microgram,
+    Milligram,
+    Centigram,
+    Decigram,
+    Decagram,
+    Hectogram,
+    Kilogram,
+    Megagram,
+    Gigagram,
+    Teragram,
+    Petagram,
+    Exagram,
+    Zettagram,
+    Yottagram,
+    Tonne,
+    Carat,
+    Grain,
+    Pound,
+    Ounce,
+    Stone,
+    ShortTon,
+    LongTon,
+    AtomicMassUnit,
+    SolarMass
+);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use approx::{assert_abs_diff_eq, assert_relative_eq};
+    use proptest::prelude::*;
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Basic conversions
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    #[test]
+    fn gram_to_kilogram() {
+        let g = Grams::new(1000.0);
+        let kg = g.to::<Kilogram>();
+        assert_abs_diff_eq!(kg.value(), 1.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn kilogram_to_gram() {
+        let kg = Kilograms::new(1.0);
+        let g = kg.to::<Gram>();
+        assert_abs_diff_eq!(g.value(), 1000.0, epsilon = 1e-9);
+    }
+
+    #[test]
+    fn solar_mass_to_grams() {
+        let sm = SolarMasses::new(1.0);
+        let g = sm.to::<Gram>();
+        // 1 M☉ ≈ 1.988416e33 grams
+        assert_relative_eq!(g.value(), 1.988416e33, max_relative = 1e-5);
+    }
+
+    #[test]
+    fn solar_mass_to_kilograms() {
+        let sm = SolarMasses::new(1.0);
+        let kg = sm.to::<Kilogram>();
+        // 1 M☉ ≈ 1.988416e30 kg
+        assert_relative_eq!(kg.value(), 1.988416e30, max_relative = 1e-5);
+    }
+
+    #[test]
+    fn kilograms_to_solar_mass() {
+        // Earth mass ≈ 5.97e24 kg ≈ 3e-6 M☉
+        let earth_kg = Kilograms::new(5.97e24);
+        let earth_sm = earth_kg.to::<SolarMass>();
+        assert_relative_eq!(earth_sm.value(), 3.0e-6, max_relative = 0.01);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Solar mass sanity checks
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    #[test]
+    fn solar_mass_ratio_sanity() {
+        // 1 M☉ = 1.988416e33 g, so RATIO should be that value
+        assert_relative_eq!(SolarMass::RATIO, 1.988416e33, max_relative = 1e-5);
+    }
+
+    #[test]
+    fn solar_mass_order_of_magnitude() {
+        // The Sun's mass is about 2e30 kg
+        let sun = SolarMasses::new(1.0);
+        let kg = sun.to::<Kilogram>();
+        assert!(kg.value() > 1e30);
+        assert!(kg.value() < 1e31);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Roundtrip conversions
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    #[test]
+    fn roundtrip_g_kg() {
+        let original = Grams::new(5000.0);
+        let converted = original.to::<Kilogram>();
+        let back = converted.to::<Gram>();
+        assert_abs_diff_eq!(back.value(), original.value(), epsilon = 1e-9);
+    }
+
+    #[test]
+    fn roundtrip_kg_solar() {
+        let original = Kilograms::new(1e30);
+        let converted = original.to::<SolarMass>();
+        let back = converted.to::<Kilogram>();
+        assert_relative_eq!(back.value(), original.value(), max_relative = 1e-12);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Property-based tests
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    proptest! {
+        #[test]
+        fn prop_roundtrip_g_kg(g in 1e-6..1e6f64) {
+            let original = Grams::new(g);
+            let converted = original.to::<Kilogram>();
+            let back = converted.to::<Gram>();
+            prop_assert!((back.value() - original.value()).abs() < 1e-9 * g.abs().max(1.0));
+        }
+
+        #[test]
+        fn prop_g_kg_ratio(g in 1e-6..1e6f64) {
+            let grams = Grams::new(g);
+            let kg = grams.to::<Kilogram>();
+            // 1000 g = 1 kg
+            prop_assert!((grams.value() / kg.value() - 1000.0).abs() < 1e-9);
+        }
+    }
+
+    // ─── Non-SI mass units ──────────────────────────────────────────────────
+
+    #[test]
+    fn tonne_to_kilogram() {
+        let t = Tonnes::new(1.0);
+        let kg = t.to::<Kilogram>();
+        assert_relative_eq!(kg.value(), 1_000.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn carat_to_gram() {
+        let ct = Carats::new(5.0);
+        let g = ct.to::<Gram>();
+        // 1 ct = 0.2 g
+        assert_relative_eq!(g.value(), 1.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn grain_to_milligram() {
+        let gr = Grains::new(1.0);
+        let mg = gr.to::<Milligram>();
+        // ratio in code: 6_479_891 / 1_000_000_000 g = 6.479891 mg
+        assert_relative_eq!(mg.value(), 6.479_891, max_relative = 1e-6);
+    }
+
+    #[test]
+    fn pound_to_gram() {
+        let lb = Pounds::new(1.0);
+        let g = lb.to::<Gram>();
+        // 1 lb = 453.59237 g
+        assert_relative_eq!(g.value(), 453.592_37, max_relative = 1e-9);
+    }
+
+    #[test]
+    fn ounce_to_gram() {
+        let oz = Ounces::new(16.0);
+        let g = oz.to::<Gram>();
+        // 16 oz = 1 lb = 453.59237 g
+        assert_relative_eq!(g.value(), 453.592_37, max_relative = 1e-9);
+    }
+
+    #[test]
+    fn stone_to_pound() {
+        let st = Stones::new(1.0);
+        let lb = st.to::<Pound>();
+        // 1 st = 14 lb
+        assert_relative_eq!(lb.value(), 14.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn short_ton_to_pound() {
+        let ton = ShortTons::new(1.0);
+        let lb = ton.to::<Pound>();
+        // 1 US short ton = 2000 lb
+        assert_relative_eq!(lb.value(), 2000.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn long_ton_to_pound() {
+        let ton = LongTons::new(1.0);
+        let lb = ton.to::<Pound>();
+        // 1 UK long ton = 2240 lb
+        assert_relative_eq!(lb.value(), 2240.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn atomic_mass_unit_to_gram() {
+        // 1 u ≈ 1.660539e-24 g
+        let u = AtomicMassUnits::new(1.0);
+        let g = u.to::<Gram>();
+        assert_relative_eq!(g.value(), 1.660_539_068_92e-24, max_relative = 1e-6);
+    }
+
+    // ─── SI gram-prefix sampling ────────────────────────────────────────────
+
+    #[test]
+    fn milligram_to_gram() {
+        let mg = Milligrams::new(1000.0);
+        let g = mg.to::<Gram>();
+        assert_relative_eq!(g.value(), 1.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn microgram_to_milligram() {
+        let ug = Micrograms::new(1000.0);
+        let mg = ug.to::<Milligram>();
+        assert_relative_eq!(mg.value(), 1.0, max_relative = 1e-12);
+    }
+
+    #[test]
+    fn symbols_are_correct() {
+        assert_eq!(Kilogram::SYMBOL, "kg");
+        assert_eq!(Gram::SYMBOL, "g");
+        assert_eq!(Pound::SYMBOL, "lb");
+        assert_eq!(Tonne::SYMBOL, "t");
+    }
+}

package/qtty-js/qtty/qtty-core/src/units/mod.rs

@@ -0,0 +1,26 @@
+//! Predefined unit modules grouped by dimension.
+//!
+//! `qtty-core` ships a small set of built-in units so that conversions and formatting work out of the box without
+//! downstream crates having to fight Rust’s orphan rules.
+//!
+//! ## Modules
+//!
+//! - [`angular`]: angle units plus wrapping and trig helpers.
+//! - [`time`]: time units (SI second is canonical scaling unit).
+//! - [`length`]: length units (SI metre is canonical scaling unit) plus astronomy/geodesy helpers.
+//! - [`mass`]: mass units (gram is canonical scaling unit).
+//! - [`power`]: power units (watt is canonical scaling unit).
+//! - [`velocity`]: velocity aliases (`Length / Time`) built from [`length`] and [`time`].
+//! - [`frequency`]: angular frequency aliases (`Angular / Time`) built from [`angular`] and [`time`].
+//! - [`unitless`]: helpers for dimensionless quantities.
+
+pub mod angular;
+pub mod area;
+pub mod frequency;
+pub mod length;
+pub mod mass;
+pub mod power;
+pub mod time;
+pub mod unitless;
+pub mod velocity;
+pub mod volume;