siderust-js 0.1.0

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

@@ -0,0 +1,294 @@
+//! JSON serialization/deserialization FFI functions.
+//!
+//! Provides `extern "C"` functions for serializing and deserializing
+//! [`QttyQuantity`] values to/from JSON, as well as a companion
+//! `qtty_string_free` for releasing heap-allocated C strings returned by
+//! these functions.
+//!
+//! # JSON formats
+//!
+//! * **value-only** (`qtty_quantity_to/from_json_value`): a bare JSON number,
+//!   e.g. `123.456`.
+//! * **full object** (`qtty_quantity_to/from_json`): a JSON object with
+//!   `"value"` (f64) and `"unit_id"` (u32) fields,
+//!   e.g. `{"value":123.456,"unit_id":10001}`.
+
+use crate::types::{
+    QttyQuantity, UnitId, QTTY_ERR_INVALID_VALUE, QTTY_ERR_NULL_OUT, QTTY_ERR_UNKNOWN_UNIT, QTTY_OK,
+};
+use core::ffi::c_char;
+use std::ffi::{CStr, CString};
+
+// =============================================================================
+// Helper macro (mirrors the one in ffi.rs)
+// =============================================================================
+
+macro_rules! catch_panic {
+    ($default:expr, $body:expr) => {{
+        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| $body)) {
+            Ok(result) => result,
+            Err(_) => $default,
+        }
+    }};
+}
+
+// =============================================================================
+// String management
+// =============================================================================
+
+/// Frees a C string previously returned by a `qtty_quantity_to_json*` function.
+///
+/// Passing a null pointer is safe and is a no-op.
+///
+/// # Safety
+///
+/// The pointer **must** have been returned by `qtty_quantity_to_json` or
+/// `qtty_quantity_to_json_value` and must not be freed more than once.
+#[no_mangle]
+pub unsafe extern "C" fn qtty_string_free(s: *mut c_char) {
+    if !s.is_null() {
+        // SAFETY: Pointer was produced by `CString::into_raw` in this crate.
+        unsafe { drop(CString::from_raw(s)) }
+    }
+}
+
+// =============================================================================
+// Value-only JSON (bare number)
+// =============================================================================
+
+/// Serializes only the numeric value of a quantity as a JSON number string.
+///
+/// On success, `*out_json` is set to a heap-allocated NUL-terminated C string
+/// (e.g. `"123.456789"`) that the caller **must** release with
+/// [`qtty_string_free`].
+///
+/// # Returns
+///
+/// * `QTTY_OK` on success.
+/// * `QTTY_ERR_NULL_OUT` if `out_json` is null.
+/// * `QTTY_ERR_INVALID_VALUE` if serialization fails.
+///
+/// # Safety
+///
+/// `out_json` must point to a writable `*mut c_char` location.
+#[no_mangle]
+pub unsafe extern "C" fn qtty_quantity_to_json_value(
+    src: QttyQuantity,
+    out_json: *mut *mut c_char,
+) -> i32 {
+    catch_panic!(QTTY_ERR_UNKNOWN_UNIT, {
+        if out_json.is_null() {
+            return QTTY_ERR_NULL_OUT;
+        }
+
+        let s = match serde_json::to_string(&src.value) {
+            Ok(s) => s,
+            Err(_) => return QTTY_ERR_INVALID_VALUE,
+        };
+
+        match CString::new(s) {
+            Ok(c) => {
+                // SAFETY: `out_json` is not null (checked above).
+                unsafe { *out_json = c.into_raw() };
+                QTTY_OK
+            }
+            Err(_) => QTTY_ERR_INVALID_VALUE,
+        }
+    })
+}
+
+/// Deserializes a JSON number string into a quantity with the given unit.
+///
+/// # Returns
+///
+/// * `QTTY_OK` on success.
+/// * `QTTY_ERR_NULL_OUT` if either `json` or `out` is null.
+/// * `QTTY_ERR_INVALID_VALUE` if `json` is not a valid JSON number.
+///
+/// # Safety
+///
+/// `json` must be a valid NUL-terminated C string.
+/// `out` must point to a writable [`QttyQuantity`] location.
+#[no_mangle]
+pub unsafe extern "C" fn qtty_quantity_from_json_value(
+    unit: UnitId,
+    json: *const c_char,
+    out: *mut QttyQuantity,
+) -> i32 {
+    catch_panic!(QTTY_ERR_UNKNOWN_UNIT, {
+        if json.is_null() || out.is_null() {
+            return QTTY_ERR_NULL_OUT;
+        }
+
+        // SAFETY: Caller guarantees `json` is a valid NUL-terminated string.
+        let json_str = match unsafe { CStr::from_ptr(json) }.to_str() {
+            Ok(s) => s,
+            Err(_) => return QTTY_ERR_INVALID_VALUE,
+        };
+
+        match serde_json::from_str::<f64>(json_str) {
+            Ok(value) => {
+                // SAFETY: `out` is not null (checked above).
+                unsafe { *out = QttyQuantity::new(value, unit) };
+                QTTY_OK
+            }
+            Err(_) => QTTY_ERR_INVALID_VALUE,
+        }
+    })
+}
+
+// =============================================================================
+// Full-object JSON  {"value":<f64>, "unit_id":<u32>}
+// =============================================================================
+
+/// Serializes a quantity as a JSON object `{"value":<f64>,"unit_id":<u32>}`.
+///
+/// On success, `*out_json` is set to a heap-allocated NUL-terminated C string
+/// that the caller **must** release with [`qtty_string_free`].
+///
+/// # Returns
+///
+/// * `QTTY_OK` on success.
+/// * `QTTY_ERR_NULL_OUT` if `out_json` is null.
+/// * `QTTY_ERR_INVALID_VALUE` if serialization fails.
+///
+/// # Safety
+///
+/// `out_json` must point to a writable `*mut c_char` location.
+#[no_mangle]
+pub unsafe extern "C" fn qtty_quantity_to_json(
+    src: QttyQuantity,
+    out_json: *mut *mut c_char,
+) -> i32 {
+    catch_panic!(QTTY_ERR_UNKNOWN_UNIT, {
+        if out_json.is_null() {
+            return QTTY_ERR_NULL_OUT;
+        }
+
+        let obj = serde_json::json!({
+            "value": src.value,
+            "unit_id": src.unit as u32,
+        });
+
+        let s = match serde_json::to_string(&obj) {
+            Ok(s) => s,
+            Err(_) => return QTTY_ERR_INVALID_VALUE,
+        };
+
+        match CString::new(s) {
+            Ok(c) => {
+                // SAFETY: `out_json` is not null (checked above).
+                unsafe { *out_json = c.into_raw() };
+                QTTY_OK
+            }
+            Err(_) => QTTY_ERR_INVALID_VALUE,
+        }
+    })
+}
+
+/// Deserializes a JSON object `{"value":<f64>,"unit_id":<u32>}` into a quantity.
+///
+/// # Returns
+///
+/// * `QTTY_OK` on success.
+/// * `QTTY_ERR_NULL_OUT` if either `json` or `out` is null.
+/// * `QTTY_ERR_INVALID_VALUE` if `json` is not a valid JSON object with the
+///   expected fields.
+/// * `QTTY_ERR_UNKNOWN_UNIT` if the `unit_id` field does not map to a known unit.
+///
+/// # Safety
+///
+/// `json` must be a valid NUL-terminated C string.
+/// `out` must point to a writable [`QttyQuantity`] location.
+#[no_mangle]
+pub unsafe extern "C" fn qtty_quantity_from_json(
+    json: *const c_char,
+    out: *mut QttyQuantity,
+) -> i32 {
+    catch_panic!(QTTY_ERR_UNKNOWN_UNIT, {
+        if json.is_null() || out.is_null() {
+            return QTTY_ERR_NULL_OUT;
+        }
+
+        // SAFETY: Caller guarantees `json` is a valid NUL-terminated string.
+        let json_str = match unsafe { CStr::from_ptr(json) }.to_str() {
+            Ok(s) => s,
+            Err(_) => return QTTY_ERR_INVALID_VALUE,
+        };
+
+        #[derive(serde::Deserialize)]
+        struct QtyJson {
+            value: f64,
+            unit_id: u32,
+        }
+
+        match serde_json::from_str::<QtyJson>(json_str) {
+            Ok(q) => match UnitId::from_u32(q.unit_id) {
+                Some(unit) => {
+                    // SAFETY: `out` is not null (checked above).
+                    unsafe { *out = QttyQuantity::new(q.value, unit) };
+                    QTTY_OK
+                }
+                None => QTTY_ERR_UNKNOWN_UNIT,
+            },
+            Err(_) => QTTY_ERR_INVALID_VALUE,
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_to_json_value_roundtrip() {
+        let src = QttyQuantity::new(123.456, UnitId::Meter);
+        let mut ptr: *mut c_char = std::ptr::null_mut();
+
+        let status = unsafe { qtty_quantity_to_json_value(src, &mut ptr) };
+        assert_eq!(status, QTTY_OK);
+        assert!(!ptr.is_null());
+
+        let mut out = QttyQuantity::default();
+        let status2 = unsafe { qtty_quantity_from_json_value(UnitId::Meter, ptr, &mut out) };
+        unsafe { qtty_string_free(ptr) };
+
+        assert_eq!(status2, QTTY_OK);
+        assert!((out.value - 123.456).abs() < 1e-12);
+        assert_eq!(out.unit, UnitId::Meter);
+    }
+
+    #[test]
+    fn test_to_json_roundtrip() {
+        let src = QttyQuantity::new(1.5, UnitId::Kilometer);
+        let mut ptr: *mut c_char = std::ptr::null_mut();
+
+        let status = unsafe { qtty_quantity_to_json(src, &mut ptr) };
+        assert_eq!(status, QTTY_OK);
+        assert!(!ptr.is_null());
+
+        let mut out = QttyQuantity::default();
+        let status2 = unsafe { qtty_quantity_from_json(ptr, &mut out) };
+        unsafe { qtty_string_free(ptr) };
+
+        assert_eq!(status2, QTTY_OK);
+        assert!((out.value - 1.5).abs() < 1e-12);
+        assert_eq!(out.unit, UnitId::Kilometer);
+    }
+
+    #[test]
+    fn test_from_json_value_invalid_input() {
+        let bad_json = std::ffi::CString::new("not a number").unwrap();
+        let mut out = QttyQuantity::default();
+
+        let status =
+            unsafe { qtty_quantity_from_json_value(UnitId::Meter, bad_json.as_ptr(), &mut out) };
+        assert_eq!(status, QTTY_ERR_INVALID_VALUE);
+    }
+
+    #[test]
+    fn test_string_free_null_is_noop() {
+        // Must not crash
+        unsafe { qtty_string_free(std::ptr::null_mut()) };
+    }
+}

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

@@ -0,0 +1,310 @@
+//! Helper functions and trait implementations for downstream crate integration.
+//!
+//! This module provides pre-implemented conversions between `qtty` types and [`QttyQuantity`],
+//! making it easy for downstream Rust crates to integrate with the FFI layer.
+//!
+//! # Auto-generated conversions
+//!
+//! `From`/`TryFrom` implementations are auto-generated at build time from `units.csv` for
+//! all units that have a corresponding Rust type mapping. This covers the vast majority of
+//! units in the registry.
+//!
+//! Additional unit conversions can be implemented in downstream crates using the
+//! [`impl_unit_ffi!`] macro.
+//!
+//! # Usage
+//!
+//! ## Converting to FFI format
+//!
+//! ```rust
+//! use qtty::length::Meters;
+//! use qtty_ffi::QttyQuantity;
+//!
+//! let meters = Meters::new(1000.0);
+//! let ffi_qty: QttyQuantity = meters.into();
+//! ```
+//!
+//! ## Converting from FFI format
+//!
+//! ```rust
+//! use qtty::length::Kilometers;
+//! use qtty_ffi::{QttyQuantity, UnitId};
+//!
+//! // A quantity received from FFI (could be in any compatible unit)
+//! let ffi_qty = QttyQuantity::new(1000.0, UnitId::Meter);
+//!
+//! // Convert to Kilometers (automatic unit conversion happens)
+//! let km: Kilometers = ffi_qty.try_into().unwrap();
+//! assert!((km.value() - 1.0).abs() < 1e-12);
+//! ```
+//!
+//! ## Error handling
+//!
+//! Conversion from [`QttyQuantity`] can fail if the dimensions are incompatible:
+//!
+//! ```rust
+//! use qtty::length::Meters;
+//! use qtty_ffi::{QttyQuantity, UnitId, QTTY_ERR_INCOMPATIBLE_DIM};
+//!
+//! let time_qty = QttyQuantity::new(60.0, UnitId::Second);
+//! let result: Result<Meters, i32> = time_qty.try_into();
+//! assert_eq!(result, Err(QTTY_ERR_INCOMPATIBLE_DIM));
+//! ```
+
+// Auto-generated From/TryFrom impls for all units with Rust type mappings.
+// Generated by build.rs from units.csv.
+include!(concat!(env!("OUT_DIR"), "/unit_conversions.rs"));
+
+// =============================================================================
+// Explicit Helper Functions (convenience API for common units)
+// =============================================================================
+
+use crate::QttyQuantity;
+
+/// Converts `Meters` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn meters_into_ffi(m: qtty::length::Meters) -> QttyQuantity {
+    m.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Meters`.
+///
+/// Returns an error if the quantity's unit is not length-compatible.
+#[inline]
+pub fn try_into_meters(q: QttyQuantity) -> Result<qtty::length::Meters, i32> {
+    q.try_into()
+}
+
+/// Converts `Kilometers` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn kilometers_into_ffi(km: qtty::length::Kilometers) -> QttyQuantity {
+    km.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Kilometers`.
+///
+/// Returns an error if the quantity's unit is not length-compatible.
+#[inline]
+pub fn try_into_kilometers(q: QttyQuantity) -> Result<qtty::length::Kilometers, i32> {
+    q.try_into()
+}
+
+/// Converts `Seconds` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn seconds_into_ffi(s: qtty::time::Seconds) -> QttyQuantity {
+    s.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Seconds`.
+///
+/// Returns an error if the quantity's unit is not time-compatible.
+#[inline]
+pub fn try_into_seconds(q: QttyQuantity) -> Result<qtty::time::Seconds, i32> {
+    q.try_into()
+}
+
+/// Converts `Minutes` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn minutes_into_ffi(m: qtty::time::Minutes) -> QttyQuantity {
+    m.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Minutes`.
+///
+/// Returns an error if the quantity's unit is not time-compatible.
+#[inline]
+pub fn try_into_minutes(q: QttyQuantity) -> Result<qtty::time::Minutes, i32> {
+    q.try_into()
+}
+
+/// Converts `Hours` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn hours_into_ffi(h: qtty::time::Hours) -> QttyQuantity {
+    h.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Hours`.
+///
+/// Returns an error if the quantity's unit is not time-compatible.
+#[inline]
+pub fn try_into_hours(q: QttyQuantity) -> Result<qtty::time::Hours, i32> {
+    q.try_into()
+}
+
+/// Converts `Days` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn days_into_ffi(d: qtty::time::Days) -> QttyQuantity {
+    d.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Days`.
+///
+/// Returns an error if the quantity's unit is not time-compatible.
+#[inline]
+pub fn try_into_days(q: QttyQuantity) -> Result<qtty::time::Days, i32> {
+    q.try_into()
+}
+
+/// Converts `Radians` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn radians_into_ffi(r: qtty::angular::Radians) -> QttyQuantity {
+    r.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Radians`.
+///
+/// Returns an error if the quantity's unit is not angle-compatible.
+#[inline]
+pub fn try_into_radians(q: QttyQuantity) -> Result<qtty::angular::Radians, i32> {
+    q.try_into()
+}
+
+/// Converts `Degrees` to an FFI-safe `QttyQuantity`.
+#[inline]
+pub fn degrees_into_ffi(d: qtty::angular::Degrees) -> QttyQuantity {
+    d.into()
+}
+
+/// Attempts to convert a `QttyQuantity` to `Degrees`.
+///
+/// Returns an error if the quantity's unit is not angle-compatible.
+#[inline]
+pub fn try_into_degrees(q: QttyQuantity) -> Result<qtty::angular::Degrees, i32> {
+    q.try_into()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::UnitId;
+    use crate::QTTY_ERR_INCOMPATIBLE_DIM;
+    use approx::assert_relative_eq;
+    use core::f64::consts::PI;
+
+    #[test]
+    fn test_meters_roundtrip() {
+        let original = qtty::length::Meters::new(42.5);
+        let ffi: QttyQuantity = original.into();
+        let back: qtty::length::Meters = ffi.try_into().unwrap();
+        assert_relative_eq!(back.value(), 42.5, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_kilometers_roundtrip() {
+        let original = qtty::length::Kilometers::new(1.5);
+        let ffi: QttyQuantity = original.into();
+        let back: qtty::length::Kilometers = ffi.try_into().unwrap();
+        assert_relative_eq!(back.value(), 1.5, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_meters_to_kilometers_via_ffi() {
+        let meters = qtty::length::Meters::new(1000.0);
+        let ffi: QttyQuantity = meters.into();
+        let km: qtty::length::Kilometers = ffi.try_into().unwrap();
+        assert_relative_eq!(km.value(), 1.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_seconds_roundtrip() {
+        let original = qtty::time::Seconds::new(3600.0);
+        let ffi: QttyQuantity = original.into();
+        let back: qtty::time::Seconds = ffi.try_into().unwrap();
+        assert_relative_eq!(back.value(), 3600.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_hours_to_seconds_via_ffi() {
+        let hours = qtty::time::Hours::new(1.0);
+        let ffi: QttyQuantity = hours.into();
+        let secs: qtty::time::Seconds = ffi.try_into().unwrap();
+        assert_relative_eq!(secs.value(), 3600.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_degrees_to_radians_via_ffi() {
+        let degrees = qtty::angular::Degrees::new(180.0);
+        let ffi: QttyQuantity = degrees.into();
+        let radians: qtty::angular::Radians = ffi.try_into().unwrap();
+        assert_relative_eq!(radians.value(), PI, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_incompatible_conversion_fails() {
+        let meters = qtty::length::Meters::new(100.0);
+        let ffi: QttyQuantity = meters.into();
+        let result: Result<qtty::time::Seconds, i32> = ffi.try_into();
+        assert_eq!(result, Err(QTTY_ERR_INCOMPATIBLE_DIM));
+    }
+
+    #[test]
+    fn test_explicit_helper_functions() {
+        let m = qtty::length::Meters::new(1000.0);
+        let ffi = meters_into_ffi(m);
+        let km = try_into_kilometers(ffi).unwrap();
+        assert_relative_eq!(km.value(), 1.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn test_all_helper_functions_cover_unit_variants() {
+        use qtty::angular::{Degrees, Radians};
+        use qtty::length::{Kilometers, Meters};
+        use qtty::time::{Days, Hours, Minutes, Seconds};
+
+        let meters_qty = meters_into_ffi(Meters::new(12.0));
+        assert_eq!(meters_qty.unit, UnitId::Meter);
+        assert_relative_eq!(meters_qty.value, 12.0, epsilon = 1e-12);
+
+        let kilometers_qty = kilometers_into_ffi(Kilometers::new(3.0));
+        assert_eq!(kilometers_qty.unit, UnitId::Kilometer);
+        assert_relative_eq!(kilometers_qty.value, 3.0, epsilon = 1e-12);
+
+        let meters_from_kilometers = try_into_meters(kilometers_qty).unwrap();
+        assert_relative_eq!(meters_from_kilometers.value(), 3000.0, epsilon = 1e-12);
+
+        let kilometers_from_meters = try_into_kilometers(meters_qty).unwrap();
+        assert_relative_eq!(kilometers_from_meters.value(), 0.012, epsilon = 1e-12);
+
+        let seconds_qty = seconds_into_ffi(Seconds::new(90.0));
+        assert_eq!(seconds_qty.unit, UnitId::Second);
+        assert_relative_eq!(seconds_qty.value, 90.0, epsilon = 1e-12);
+
+        let minutes_qty = minutes_into_ffi(Minutes::new(2.5));
+        assert_eq!(minutes_qty.unit, UnitId::Minute);
+        assert_relative_eq!(minutes_qty.value, 2.5, epsilon = 1e-12);
+
+        let seconds_from_minutes = try_into_seconds(minutes_qty).unwrap();
+        assert_relative_eq!(seconds_from_minutes.value(), 150.0, epsilon = 1e-12);
+
+        let minutes_from_seconds = try_into_minutes(seconds_qty).unwrap();
+        assert_relative_eq!(minutes_from_seconds.value(), 1.5, epsilon = 1e-12);
+
+        let hours_qty = hours_into_ffi(Hours::new(4.0));
+        assert_eq!(hours_qty.unit, UnitId::Hour);
+        assert_relative_eq!(hours_qty.value, 4.0, epsilon = 1e-12);
+
+        let hours_from_minutes = try_into_hours(minutes_into_ffi(Minutes::new(180.0))).unwrap();
+        assert_relative_eq!(hours_from_minutes.value(), 3.0, epsilon = 1e-12);
+
+        let days_qty = days_into_ffi(Days::new(1.25));
+        assert_eq!(days_qty.unit, UnitId::Day);
+        assert_relative_eq!(days_qty.value, 1.25, epsilon = 1e-12);
+
+        let days_from_hours = try_into_days(hours_into_ffi(Hours::new(48.0))).unwrap();
+        assert_relative_eq!(days_from_hours.value(), 2.0, epsilon = 1e-12);
+
+        let radians_qty = radians_into_ffi(Radians::new(PI));
+        assert_eq!(radians_qty.unit, UnitId::Radian);
+        assert_relative_eq!(radians_qty.value, PI, epsilon = 1e-12);
+
+        let degrees_qty = degrees_into_ffi(Degrees::new(270.0));
+        assert_eq!(degrees_qty.unit, UnitId::Degree);
+        assert_relative_eq!(degrees_qty.value, 270.0, epsilon = 1e-12);
+
+        let radians_from_degrees = try_into_radians(degrees_qty).unwrap();
+        assert_relative_eq!(radians_from_degrees.value(), 1.5 * PI, epsilon = 1e-12);
+
+        let degrees_from_radians = try_into_degrees(radians_qty).unwrap();
+        assert_relative_eq!(degrees_from_radians.value(), 180.0, epsilon = 1e-12);
+    }
+}