siderust-js 0.1.0

package/qtty-js/qtty/qtty-ffi/src/types.rs

@@ -0,0 +1,620 @@
+//! ABI-stable FFI types for `qtty` quantities.
+//!
+//! This module defines the `#[repr(C)]` and `#[repr(u32)]` types that form the stable C ABI
+//! for cross-language interoperability. These types are designed to be safe to pass across
+//! FFI boundaries.
+//!
+//! # ABI Stability Contract
+//!
+//! The discriminant values for [`UnitId`] and [`DimensionId`] are part of the ABI contract
+//! and **MUST NEVER CHANGE** once assigned. New variants may be added with new discriminant
+//! values, but existing values must remain stable across all versions.
+
+use core::ffi::c_char;
+use serde::{Deserialize, Serialize};
+
+// =============================================================================
+// Status Codes
+// =============================================================================
+
+/// Success status code.
+pub const QTTY_OK: i32 = 0;
+
+/// Error: the provided unit ID is not recognized/valid.
+pub const QTTY_ERR_UNKNOWN_UNIT: i32 = -1;
+
+/// Error: conversion requested between incompatible dimensions.
+pub const QTTY_ERR_INCOMPATIBLE_DIM: i32 = -2;
+
+/// Error: a required output pointer was null.
+pub const QTTY_ERR_NULL_OUT: i32 = -3;
+
+/// Error: the provided value is invalid (reserved for future use).
+pub const QTTY_ERR_INVALID_VALUE: i32 = -4;
+
+/// Error: the provided output buffer is too small.
+pub const QTTY_ERR_BUFFER_TOO_SMALL: i32 = -5;
+
+// =============================================================================
+// Format Flags (for qtty_quantity_format)
+// =============================================================================
+
+/// Format flag: default decimal notation (e.g. `"1234.57 m"`).
+pub const QTTY_FMT_DEFAULT: u32 = 0;
+
+/// Format flag: scientific notation with lowercase `e` (e.g. `"1.23e3 m"`).
+pub const QTTY_FMT_LOWER_EXP: u32 = 1;
+
+/// Format flag: scientific notation with uppercase `E` (e.g. `"1.23E3 m"`).
+pub const QTTY_FMT_UPPER_EXP: u32 = 2;
+
+// =============================================================================
+// Dimension Identifiers
+// =============================================================================
+
+/// Dimension identifier for FFI.
+///
+/// Represents the physical dimension of a quantity. All discriminant values are
+/// explicitly assigned and are part of the ABI contract.
+///
+/// # ABI Contract
+///
+/// **Discriminant values must never change.** New dimensions may be added with
+/// new explicit discriminant values.
+#[repr(u32)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum DimensionId {
+    /// Length dimension (e.g., meters, kilometers).
+    Length = 1,
+    /// Time dimension (e.g., seconds, hours).
+    Time = 2,
+    /// Angle dimension (e.g., radians, degrees).
+    Angle = 3,
+    /// Mass dimension (e.g., grams, kilograms).
+    Mass = 4,
+    /// Power dimension (e.g., watts, kilowatts).
+    Power = 5,
+}
+
+// =============================================================================
+// Unit Identifiers
+// =============================================================================
+
+// =============================================================================
+// Unit Identifiers
+// =============================================================================
+
+// The UnitId enum is generated by build.rs from qtty-core unit definitions.
+// All discriminant values are explicitly assigned and are part of the ABI contract.
+// Discriminant encoding: DSSCC where D=dimension (1 digit), SS=system (2 digits), CC=counter (2 digits)
+// Units are grouped by dimension with ranges:
+// - Length units: 1xxxx (10000-19999), Time units: 2xxxx (20000-29999), Angle units: 3xxxx (30000-39999)
+// - Mass units: 4xxxx (40000-49999), Power units: 5xxxx (50000-59999)
+include!(concat!(env!("OUT_DIR"), "/unit_id_enum.rs"));
+
+impl UnitId {
+    /// Returns the unit name as a static NUL-terminated C string.
+    ///
+    /// This is safe to call from C code and returns a pointer to static memory.
+    #[inline]
+    pub const fn name_cstr(&self) -> *const c_char {
+        include!(concat!(env!("OUT_DIR"), "/unit_names_cstr.rs"))
+    }
+
+    /// Returns the unit name as a Rust string slice.
+    #[inline]
+    pub const fn name(&self) -> &'static str {
+        include!(concat!(env!("OUT_DIR"), "/unit_names.rs"))
+    }
+
+    /// Returns the unit symbol as a Rust string slice (e.g., "m", "km", "s").
+    #[inline]
+    pub const fn symbol(&self) -> &'static str {
+        include!(concat!(env!("OUT_DIR"), "/unit_symbols.rs"))
+    }
+
+    /// Attempts to create a `UnitId` from a raw `u32` discriminant value.
+    ///
+    /// Returns `None` if the value does not correspond to a valid unit.
+    #[inline]
+    pub const fn from_u32(value: u32) -> Option<Self> {
+        include!(concat!(env!("OUT_DIR"), "/unit_from_u32.rs"))
+    }
+}
+
+// =============================================================================
+// Quantity Carrier Type
+// =============================================================================
+
+/// A POD quantity carrier type suitable for FFI.
+///
+/// This struct represents a physical quantity as a value paired with its unit.
+/// It is `#[repr(C)]` to ensure a stable, predictable memory layout across
+/// language boundaries.
+///
+/// # Memory Layout
+///
+/// - `value`: 8 bytes (f64)
+/// - `unit`: 4 bytes (u32 via UnitId)
+/// - Padding: 4 bytes (for alignment)
+/// - Total: 16 bytes on most platforms
+///
+/// # Example
+///
+/// ```rust
+/// use qtty_ffi::{QttyQuantity, UnitId};
+///
+/// let q = QttyQuantity {
+///     value: 1000.0,
+///     unit: UnitId::Meter,
+/// };
+/// ```
+#[repr(C)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+pub struct QttyQuantity {
+    /// The numeric value of the quantity.
+    pub value: f64,
+    /// The unit identifier for this quantity.
+    pub unit: UnitId,
+}
+
+impl QttyQuantity {
+    /// Creates a new quantity with the given value and unit.
+    #[inline]
+    pub const fn new(value: f64, unit: UnitId) -> Self {
+        Self { value, unit }
+    }
+
+    /// Checks if this quantity is compatible with another (same dimension).
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let meters = QttyQuantity::new(100.0, UnitId::Meter);
+    /// let km = QttyQuantity::new(1.0, UnitId::Kilometer);
+    /// let seconds = QttyQuantity::new(60.0, UnitId::Second);
+    ///
+    /// assert!(meters.compatible(&km));
+    /// assert!(!meters.compatible(&seconds));
+    /// ```
+    #[inline]
+    pub fn compatible(&self, other: &Self) -> bool {
+        crate::registry::compatible(self.unit, other.unit)
+    }
+
+    /// Returns the dimension of this quantity.
+    #[inline]
+    pub fn dimension(&self) -> Option<DimensionId> {
+        crate::registry::dimension(self.unit)
+    }
+
+    /// Converts this quantity to a different unit.
+    ///
+    /// Returns `None` if the units are incompatible (different dimensions).
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let meters = QttyQuantity::new(1000.0, UnitId::Meter);
+    /// let km = meters.convert_to(UnitId::Kilometer).unwrap();
+    /// assert!((km.value - 1.0).abs() < 1e-12);
+    /// assert_eq!(km.unit, UnitId::Kilometer);
+    /// ```
+    #[inline]
+    pub fn convert_to(&self, target: UnitId) -> Option<Self> {
+        crate::registry::convert_value(self.value, self.unit, target)
+            .ok()
+            .map(|v| Self::new(v, target))
+    }
+
+    /// Adds two quantities, returning result in the left operand's unit.
+    ///
+    /// Returns `None` if the quantities have different dimensions.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let a = QttyQuantity::new(1.0, UnitId::Kilometer);
+    /// let b = QttyQuantity::new(500.0, UnitId::Meter);
+    /// let sum = a.add(&b).unwrap();
+    /// assert!((sum.value - 1.5).abs() < 1e-12);
+    /// assert_eq!(sum.unit, UnitId::Kilometer);
+    /// ```
+    #[inline]
+    pub fn add(&self, other: &Self) -> Option<Self> {
+        let other_converted = other.convert_to(self.unit)?;
+        Some(Self::new(self.value + other_converted.value, self.unit))
+    }
+
+    /// Subtracts another quantity from this one, returning result in this quantity's unit.
+    ///
+    /// Returns `None` if the quantities have different dimensions.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let a = QttyQuantity::new(2.0, UnitId::Kilometer);
+    /// let b = QttyQuantity::new(500.0, UnitId::Meter);
+    /// let diff = a.sub(&b).unwrap();
+    /// assert!((diff.value - 1.5).abs() < 1e-12);
+    /// assert_eq!(diff.unit, UnitId::Kilometer);
+    /// ```
+    #[inline]
+    pub fn sub(&self, other: &Self) -> Option<Self> {
+        let other_converted = other.convert_to(self.unit)?;
+        Some(Self::new(self.value - other_converted.value, self.unit))
+    }
+
+    /// Multiplies the quantity by a scalar value.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let q = QttyQuantity::new(5.0, UnitId::Meter);
+    /// let result = q.mul_scalar(3.0);
+    /// assert!((result.value - 15.0).abs() < 1e-12);
+    /// ```
+    #[inline]
+    pub const fn mul_scalar(&self, scalar: f64) -> Self {
+        Self::new(self.value * scalar, self.unit)
+    }
+
+    /// Divides the quantity by a scalar value.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyQuantity, UnitId};
+    ///
+    /// let q = QttyQuantity::new(15.0, UnitId::Meter);
+    /// let result = q.div_scalar(3.0);
+    /// assert!((result.value - 5.0).abs() < 1e-12);
+    /// ```
+    #[inline]
+    pub const fn div_scalar(&self, scalar: f64) -> Self {
+        Self::new(self.value / scalar, self.unit)
+    }
+
+    /// Negates the quantity value.
+    #[inline]
+    pub const fn neg(&self) -> Self {
+        Self::new(-self.value, self.unit)
+    }
+}
+
+impl Default for QttyQuantity {
+    fn default() -> Self {
+        Self {
+            value: 0.0,
+            unit: UnitId::Meter,
+        }
+    }
+}
+
+// =============================================================================
+// QttyDerivedQuantity - Compound quantities like velocity (m/s)
+// =============================================================================
+
+/// A derived quantity representing a compound unit (numerator/denominator).
+///
+/// This is useful for quantities like velocity (m/s), frequency (rad/s), etc.
+///
+/// # ABI Stability
+///
+/// This struct has `#[repr(C)]` layout:
+/// - `value` at offset 0 (8 bytes)
+/// - `numerator` at offset 8 (4 bytes)
+/// - `denominator` at offset 12 (4 bytes)
+/// - Total size: 16 bytes
+///
+/// # Example
+///
+/// ```rust
+/// use qtty_ffi::{QttyDerivedQuantity, UnitId};
+///
+/// // Create a velocity: 100 m/s
+/// let velocity = QttyDerivedQuantity::new(100.0, UnitId::Meter, UnitId::Second);
+/// assert_eq!(velocity.value, 100.0);
+/// assert_eq!(velocity.numerator, UnitId::Meter);
+/// assert_eq!(velocity.denominator, UnitId::Second);
+/// ```
+#[repr(C)]
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+pub struct QttyDerivedQuantity {
+    /// The numeric value of the derived quantity.
+    pub value: f64,
+    /// The numerator unit identifier.
+    pub numerator: UnitId,
+    /// The denominator unit identifier.
+    pub denominator: UnitId,
+}
+
+impl QttyDerivedQuantity {
+    /// Creates a new derived quantity with the given value and units.
+    #[inline]
+    pub const fn new(value: f64, numerator: UnitId, denominator: UnitId) -> Self {
+        Self {
+            value,
+            numerator,
+            denominator,
+        }
+    }
+
+    /// Returns the symbol string for this derived quantity (e.g., "m/s").
+    #[inline]
+    pub fn symbol(&self) -> String {
+        format!("{}/{}", self.numerator.symbol(), self.denominator.symbol())
+    }
+
+    /// Converts this derived quantity to different units.
+    ///
+    /// Returns `None` if the numerator or denominator dimensions are incompatible.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use qtty_ffi::{QttyDerivedQuantity, UnitId};
+    ///
+    /// // Convert 100 m/s to km/h
+    /// let velocity = QttyDerivedQuantity::new(100.0, UnitId::Meter, UnitId::Second);
+    /// let converted = velocity.convert_to(UnitId::Kilometer, UnitId::Hour).unwrap();
+    /// // 100 m/s = 360 km/h
+    /// assert!((converted.value - 360.0).abs() < 1e-9);
+    /// ```
+    pub fn convert_to(&self, target_num: UnitId, target_den: UnitId) -> Option<Self> {
+        // Check dimensional compatibility
+        let num_dim = crate::registry::dimension(self.numerator)?;
+        let den_dim = crate::registry::dimension(self.denominator)?;
+        let target_num_dim = crate::registry::dimension(target_num)?;
+        let target_den_dim = crate::registry::dimension(target_den)?;
+
+        if num_dim != target_num_dim || den_dim != target_den_dim {
+            return None;
+        }
+
+        // Convert numerator: e.g., 100 m -> ? km
+        let num_converted =
+            crate::registry::convert_value(self.value, self.numerator, target_num).ok()?;
+
+        // Convert denominator scale: e.g., 1 s -> ? h (0.000278 h)
+        // If 1 s = 0.000278 h, then dividing by that gives us the factor
+        let den_converted =
+            crate::registry::convert_value(1.0, self.denominator, target_den).ok()?;
+
+        // Result = (num in new units) / (den scale factor)
+        // 100 m = 0.1 km, 1 s = 1/3600 h
+        // 100 m/s = 0.1 km / (1/3600 h) = 0.1 * 3600 km/h = 360 km/h
+        let result_value = num_converted / den_converted;
+
+        Some(Self::new(result_value, target_num, target_den))
+    }
+
+    /// Multiplies the derived quantity by a scalar.
+    #[inline]
+    pub const fn mul_scalar(&self, scalar: f64) -> Self {
+        Self::new(self.value * scalar, self.numerator, self.denominator)
+    }
+
+    /// Divides the derived quantity by a scalar.
+    #[inline]
+    pub const fn div_scalar(&self, scalar: f64) -> Self {
+        Self::new(self.value / scalar, self.numerator, self.denominator)
+    }
+
+    /// Negates the derived quantity.
+    #[inline]
+    pub const fn neg(&self) -> Self {
+        Self::new(-self.value, self.numerator, self.denominator)
+    }
+}
+
+impl Default for QttyDerivedQuantity {
+    fn default() -> Self {
+        Self {
+            value: 0.0,
+            numerator: UnitId::Meter,
+            denominator: UnitId::Second,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn unit_id_discriminants_are_stable() {
+        // These values are part of the ABI contract and must never change
+        assert_eq!(UnitId::Meter as u32, 10011); // Length, SI, #11
+        assert_eq!(UnitId::Kilometer as u32, 10014); // Length, SI, #14
+        assert_eq!(UnitId::Second as u32, 20008); // Time, SI, #8
+        assert_eq!(UnitId::Minute as u32, 21000); // Time, Common, #0
+        assert_eq!(UnitId::Hour as u32, 21001); // Time, Common, #1
+        assert_eq!(UnitId::Day as u32, 21002); // Time, Common, #2
+        assert_eq!(UnitId::Radian as u32, 30001); // Angle, Radian, #1
+        assert_eq!(UnitId::Degree as u32, 31004); // Angle, Degree, #4
+    }
+
+    #[test]
+    fn dimension_id_discriminants_are_stable() {
+        // These values are part of the ABI contract and must never change
+        assert_eq!(DimensionId::Length as u32, 1);
+        assert_eq!(DimensionId::Time as u32, 2);
+        assert_eq!(DimensionId::Angle as u32, 3);
+    }
+
+    #[test]
+    fn unit_id_from_u32_roundtrips() {
+        for unit in [
+            UnitId::Meter,
+            UnitId::Kilometer,
+            UnitId::Second,
+            UnitId::Minute,
+            UnitId::Hour,
+            UnitId::Day,
+            UnitId::Radian,
+            UnitId::Degree,
+        ] {
+            let value = unit as u32;
+            assert_eq!(UnitId::from_u32(value), Some(unit));
+        }
+    }
+
+    #[test]
+    fn unit_id_from_u32_rejects_invalid() {
+        assert_eq!(UnitId::from_u32(0), None);
+        assert_eq!(UnitId::from_u32(9999), None);
+        assert_eq!(UnitId::from_u32(60000), None);
+        assert_eq!(UnitId::from_u32(99999), None);
+    }
+
+    #[test]
+    fn unit_names_are_not_empty() {
+        for unit in [
+            UnitId::Meter,
+            UnitId::Kilometer,
+            UnitId::Second,
+            UnitId::Minute,
+            UnitId::Hour,
+            UnitId::Day,
+            UnitId::Radian,
+            UnitId::Degree,
+        ] {
+            assert!(!unit.name().is_empty());
+        }
+    }
+
+    // ─── QttyQuantity method coverage ────────────────────────────────────────
+
+    #[test]
+    fn qtty_quantity_default() {
+        let q = QttyQuantity::default();
+        assert_eq!(q.value, 0.0);
+        assert_eq!(q.unit, UnitId::Meter);
+    }
+
+    #[test]
+    fn qtty_quantity_neg() {
+        let q = QttyQuantity::new(5.0, UnitId::Meter);
+        let n = q.neg();
+        assert_eq!(n.value, -5.0);
+        assert_eq!(n.unit, UnitId::Meter);
+    }
+
+    #[test]
+    fn qtty_quantity_mul_scalar() {
+        let q = QttyQuantity::new(4.0, UnitId::Kilometer);
+        let r = q.mul_scalar(2.5);
+        assert_eq!(r.value, 10.0);
+        assert_eq!(r.unit, UnitId::Kilometer);
+    }
+
+    #[test]
+    fn qtty_quantity_div_scalar() {
+        let q = QttyQuantity::new(15.0, UnitId::Second);
+        let r = q.div_scalar(3.0);
+        assert_eq!(r.value, 5.0);
+        assert_eq!(r.unit, UnitId::Second);
+    }
+
+    #[test]
+    fn qtty_quantity_dimension() {
+        let q = QttyQuantity::new(1.0, UnitId::Meter);
+        assert_eq!(q.dimension(), Some(DimensionId::Length));
+
+        let t = QttyQuantity::new(1.0, UnitId::Second);
+        assert_eq!(t.dimension(), Some(DimensionId::Time));
+    }
+
+    #[test]
+    fn qtty_quantity_compatible() {
+        let a = QttyQuantity::new(1.0, UnitId::Meter);
+        let b = QttyQuantity::new(1.0, UnitId::Kilometer);
+        let c = QttyQuantity::new(1.0, UnitId::Second);
+
+        assert!(a.compatible(&b));
+        assert!(!a.compatible(&c));
+    }
+
+    #[test]
+    fn qtty_quantity_add_incompatible_returns_none() {
+        let a = QttyQuantity::new(1.0, UnitId::Meter);
+        let b = QttyQuantity::new(1.0, UnitId::Second);
+        assert!(a.add(&b).is_none());
+    }
+
+    #[test]
+    fn qtty_quantity_sub_incompatible_returns_none() {
+        let a = QttyQuantity::new(1.0, UnitId::Meter);
+        let b = QttyQuantity::new(1.0, UnitId::Second);
+        assert!(a.sub(&b).is_none());
+    }
+
+    // ─── QttyDerivedQuantity method coverage ─────────────────────────────────
+
+    #[test]
+    fn qtty_derived_quantity_default() {
+        let d = QttyDerivedQuantity::default();
+        assert_eq!(d.value, 0.0);
+        assert_eq!(d.numerator, UnitId::Meter);
+        assert_eq!(d.denominator, UnitId::Second);
+    }
+
+    #[test]
+    fn qtty_derived_quantity_symbol() {
+        let d = QttyDerivedQuantity::new(1.0, UnitId::Meter, UnitId::Second);
+        let sym = d.symbol();
+        // format is "numerator_symbol/denominator_symbol"
+        assert!(sym.contains('/'), "symbol should contain '/'");
+        assert!(!sym.is_empty());
+        // Should look like "m/s"
+        assert_eq!(
+            sym,
+            format!("{}/{}", UnitId::Meter.symbol(), UnitId::Second.symbol())
+        );
+    }
+
+    #[test]
+    fn qtty_derived_quantity_mul_scalar() {
+        let d = QttyDerivedQuantity::new(10.0, UnitId::Meter, UnitId::Second);
+        let r = d.mul_scalar(3.0);
+        assert_eq!(r.value, 30.0);
+        assert_eq!(r.numerator, UnitId::Meter);
+        assert_eq!(r.denominator, UnitId::Second);
+    }
+
+    #[test]
+    fn qtty_derived_quantity_div_scalar() {
+        let d = QttyDerivedQuantity::new(30.0, UnitId::Kilometer, UnitId::Hour);
+        let r = d.div_scalar(2.0);
+        assert_eq!(r.value, 15.0);
+        assert_eq!(r.numerator, UnitId::Kilometer);
+        assert_eq!(r.denominator, UnitId::Hour);
+    }
+
+    #[test]
+    fn qtty_derived_quantity_neg() {
+        let d = QttyDerivedQuantity::new(5.0, UnitId::Meter, UnitId::Second);
+        let n = d.neg();
+        assert_eq!(n.value, -5.0);
+        assert_eq!(n.numerator, UnitId::Meter);
+        assert_eq!(n.denominator, UnitId::Second);
+    }
+
+    #[test]
+    fn qtty_derived_quantity_convert_to_incompatible_returns_none() {
+        // m/s → kg/h: numerator dimension mismatch
+        let d = QttyDerivedQuantity::new(1.0, UnitId::Meter, UnitId::Second);
+        assert!(d.convert_to(UnitId::Kilogram, UnitId::Hour).is_none());
+    }
+}