Crate qtty_ffi

Crate qtty_ffi 

Source
Expand description

C-compatible FFI bindings for qtty physical quantities and unit conversions.

qtty-ffi provides a stable C ABI for qtty, enabling interoperability with C/C++ code and other languages with C FFI support. It also provides helper types and macros for downstream Rust crates that need to expose their own FFI APIs using qtty quantities.

§Features

  • ABI-stable types: #[repr(C)] and #[repr(u32)] types safe for FFI
  • Unit registry: Mapping between FFI unit IDs and conversion factors
  • C API: extern "C" functions for quantity construction and conversion
  • Rust helpers: Macros and trait implementations for downstream integration

§Quick Start (C/C++)

Include the generated header and link against the library:

#include "qtty_ffi.h"

// Create a quantity
QttyQuantity meters;
qtty_quantity_make(1000.0, UnitId_Meter, &meters);

// Convert to kilometers
QttyQuantity kilometers;
int32_t status = qtty_quantity_convert(meters, UnitId_Kilometer, &kilometers);
if (status == QTTY_OK) {
    // kilometers.value == 1.0
}

§Quick Start (Rust)

Use the helper traits and macros for seamless conversion:

use qtty::length::{Meters, Kilometers};
use qtty_ffi::{QttyQuantity, UnitId};

// Convert Rust type to FFI
let meters = Meters::new(1000.0);
let ffi_qty: QttyQuantity = meters.into();

// Convert FFI back to Rust type (with automatic unit conversion)
let km: Kilometers = ffi_qty.try_into().unwrap();
assert!((km.value() - 1.0).abs() < 1e-12);

§ABI Stability

The following are part of the ABI contract and will never change:

New variants may be added to enums (with new discriminant values), and new functions may be added, but existing items will remain stable.

§Supported Units (v1)

§Length

§Time

§Angle

§Error Handling

All FFI functions return status codes:

§Thread Safety

All functions are thread-safe. The library contains no global mutable state.

Re-exports§

pub use helpers::days_into_ffi;
pub use helpers::degrees_into_ffi;
pub use helpers::hours_into_ffi;
pub use helpers::kilometers_into_ffi;
pub use helpers::meters_into_ffi;
pub use helpers::minutes_into_ffi;
pub use helpers::radians_into_ffi;
pub use helpers::seconds_into_ffi;
pub use helpers::try_into_days;
pub use helpers::try_into_degrees;
pub use helpers::try_into_hours;
pub use helpers::try_into_kilometers;
pub use helpers::try_into_meters;
pub use helpers::try_into_minutes;
pub use helpers::try_into_radians;
pub use helpers::try_into_seconds;

Modules§

helpers
Helper functions and trait implementations for downstream crate integration.
macros
Macros for implementing FFI conversions for qtty unit types.
registry
Unit registry and conversion logic for FFI.

Macros§

impl_unit_ffi
Implements From<$qty_type> for QttyQuantity and TryFrom<QttyQuantity> for $qty_type.

Structs§

QttyDerivedQuantity
A derived quantity representing a compound unit (numerator/denominator).
QttyQuantity
A POD quantity carrier type suitable for FFI.

Enums§

DimensionId
Dimension identifier for FFI.
UnitId
Unit identifier for FFI.

Constants§

QTTY_ERR_INCOMPATIBLE_DIM
Error: conversion requested between incompatible dimensions.
QTTY_ERR_INVALID_VALUE
Error: the provided value is invalid (reserved for future use).
QTTY_ERR_NULL_OUT
Error: a required output pointer was null.
QTTY_ERR_UNKNOWN_UNIT
Error: the provided unit ID is not recognized/valid.
QTTY_OK
Success status code.

Functions§

qtty_ffi_version
Returns the FFI ABI version.
qtty_quantity_convert⚠
Converts a quantity to a different unit.
qtty_quantity_convert_value⚠
Converts a value from one unit to another.
qtty_quantity_make⚠
Creates a new quantity with the given value and unit.
qtty_unit_dimension⚠
Gets the dimension of a unit.
qtty_unit_is_valid
Checks if a unit ID is valid (recognized by the registry).
qtty_unit_name
Gets the name of a unit as a NUL-terminated C string.
qtty_units_compatible⚠
Checks if two units are compatible (same dimension).