pamoja_ffi/

kit.rs

//! The C ABI for the goal-named helper math.
//!
//! These functions wrap [`pamoja_kit`] for callers that reach the SDK through the
//! flat C boundary: smoothing a noisy reading, holding a value with a PID,
//! switching a load with hysteresis, warning before a tank runs dry, and placing
//! a fix against a geofence.
//!
//! The helpers are infallible pure math, so unlike the transport capabilities
//! nothing here returns a status for the work itself. Each stateful helper is an
//! opaque handle whose methods document what they return for a null handle,
//! following `pamoja_mqtt_client_is_connected`. A constructor never returns null,
//! except a windowed helper's `_with_capacity` constructor given a capacity it
//! cannot keep. Helpers that answer "maybe" return a `bool` and write the value
//! through an out-parameter.
//!
//! A reading that is not a finite number is ignored by every helper that keeps
//! state, as the Rust crate documents, and an anomaly detector flags it.

use std::ptr;

use pamoja_kit::{
    deadband, imu, units, weather, Anomaly, Boundary, Calibration, Complementary, Coordinate,
    Debounce, Depletion, Edge, Geofence, Kalman, Median, Pid, Ramp, Smoother, Surge, Thermostat,
    Trend, Trigger, Window,
};

/// A latitude and longitude in degrees.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct PamojaCoordinate {
    /// Degrees north of the equator, negative for south.
    pub latitude: f64,
    /// Degrees east of the prime meridian, negative for west.
    pub longitude: f64,
}

impl From<PamojaCoordinate> for Coordinate {
    fn from(value: PamojaCoordinate) -> Self {
        Coordinate::new(value.latitude, value.longitude)
    }
}

/// Where a fix sits relative to a geofence, including the moment it crosses.
#[repr(C)]
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum PamojaBoundary {
    /// The fix is inside the fence and was inside before, or is the first fix inside.
    Inside = 0,
    /// The fix is outside the fence and was outside before, or is the first fix outside.
    Outside = 1,
    /// The fix just crossed from inside to outside: the moment to raise a breach alert.
    Exited = 2,
    /// The fix just crossed from outside back inside.
    Entered = 3,
}

impl From<Boundary> for PamojaBoundary {
    fn from(value: Boundary) -> Self {
        match value {
            Boundary::Inside => Self::Inside,
            Boundary::Outside => Self::Outside,
            Boundary::Exited => Self::Exited,
            Boundary::Entered => Self::Entered,
        }
    }
}

// Each handle below is written out rather than generated by a macro: cbindgen
// parses this source without expanding macros, so a macro-defined type would be
// referenced by the header without ever being declared in it.

/// An opaque handle to an exponential smoother.
pub struct PamojaSmoother {
    inner: Smoother,
}

/// Releases a smoother handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `smoother` must be a handle from [`pamoja_smoother_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_smoother_free(smoother: *mut PamojaSmoother) {
    if !smoother.is_null() {
        drop(Box::from_raw(smoother));
    }
}

/// An opaque handle to a PID controller.
pub struct PamojaPid {
    inner: Pid,
}

/// Releases a PID controller handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `pid` must be a handle from a PID constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_pid_free(pid: *mut PamojaPid) {
    if !pid.is_null() {
        drop(Box::from_raw(pid));
    }
}

/// An opaque handle to an on/off controller with hysteresis.
pub struct PamojaThermostat {
    inner: Thermostat,
}

/// What a trigger reports when a reading changes its state, if anything.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PamojaEdge {
    /// Nothing changed.
    None = 0,
    /// The reading just crossed the line: the condition became true.
    Set = 1,
    /// The reading just came back past the release band: the condition stopped holding.
    Cleared = 2,
}

/// An opaque handle to a threshold with hysteresis that reports its edges.
pub struct PamojaTrigger {
    inner: Trigger,
}

/// Releases a trigger handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `trigger` must be a handle from [`pamoja_trigger_above`] or [`pamoja_trigger_below`]
/// that has not already been freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_free(trigger: *mut PamojaTrigger) {
    if !trigger.is_null() {
        drop(Box::from_raw(trigger));
    }
}

/// Creates a trigger that fires when a reading rises above the line and clears once it
/// has fallen below the line by the hysteresis.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_trigger_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_above(
    threshold: f32,
    hysteresis: f32,
) -> *mut PamojaTrigger {
    Box::into_raw(Box::new(PamojaTrigger {
        inner: Trigger::above(threshold, hysteresis),
    }))
}

/// Creates a trigger that fires when a reading falls below the line and clears once it
/// has risen above the line by the hysteresis.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_trigger_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_below(
    threshold: f32,
    hysteresis: f32,
) -> *mut PamojaTrigger {
    Box::into_raw(Box::new(PamojaTrigger {
        inner: Trigger::below(threshold, hysteresis),
    }))
}

/// Feeds a reading to a trigger and returns the edge it caused.
///
/// # Returns
///
/// [`PamojaEdge::Set`] or [`PamojaEdge::Cleared`] the moment the state changes, and
/// [`PamojaEdge::None`] while nothing changed or if `trigger` is null.
///
/// # Safety
///
/// `trigger` must be a live handle from a trigger constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_update(
    trigger: *mut PamojaTrigger,
    reading: f32,
) -> PamojaEdge {
    match trigger.as_mut() {
        Some(trigger) => match trigger.inner.update(reading) {
            Some(Edge::Set) => PamojaEdge::Set,
            Some(Edge::Cleared) => PamojaEdge::Cleared,
            None => PamojaEdge::None,
        },
        None => PamojaEdge::None,
    }
}

/// Reports whether a trigger's condition currently holds.
///
/// # Returns
///
/// `true` from the reading that set the trigger until the one that clears it, or
/// `false` if `trigger` is null.
///
/// # Safety
///
/// `trigger` must be a live handle from a trigger constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_is_set(trigger: *const PamojaTrigger) -> bool {
    match trigger.as_ref() {
        Some(trigger) => trigger.inner.is_set(),
        None => false,
    }
}

/// Reads the line a trigger watches.
///
/// # Returns
///
/// The threshold it was created with, or NaN if `trigger` is null.
///
/// # Safety
///
/// `trigger` must be a live handle from a trigger constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_threshold(trigger: *const PamojaTrigger) -> f32 {
    match trigger.as_ref() {
        Some(trigger) => trigger.inner.threshold(),
        None => f32::NAN,
    }
}

/// Reads the release band on the far side of a trigger's line.
///
/// # Returns
///
/// The hysteresis it was created with, as a magnitude, or NaN if `trigger` is null.
///
/// # Safety
///
/// `trigger` must be a live handle from a trigger constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_hysteresis(trigger: *const PamojaTrigger) -> f32 {
    match trigger.as_ref() {
        Some(trigger) => trigger.inner.hysteresis(),
        None => f32::NAN,
    }
}

/// Reports whether a trigger watches a rising reading.
///
/// # Returns
///
/// `true` for a trigger from [`pamoja_trigger_above`], and `false` for one from
/// [`pamoja_trigger_below`] or if `trigger` is null.
///
/// # Safety
///
/// `trigger` must be a live handle from a trigger constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trigger_watches_above(trigger: *const PamojaTrigger) -> bool {
    match trigger.as_ref() {
        Some(trigger) => trigger.inner.watches_above(),
        None => false,
    }
}

/// Releases a thermostat handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `thermostat` must be a handle from a thermostat constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_thermostat_free(thermostat: *mut PamojaThermostat) {
    if !thermostat.is_null() {
        drop(Box::from_raw(thermostat));
    }
}

/// An opaque handle to a depletion estimator.
pub struct PamojaDepletion {
    inner: Depletion,
}

/// Releases a depletion estimator handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `depletion` must be a handle from [`pamoja_depletion_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_depletion_free(depletion: *mut PamojaDepletion) {
    if !depletion.is_null() {
        drop(Box::from_raw(depletion));
    }
}

/// An opaque handle to a one-dimensional Kalman filter.
pub struct PamojaKalman {
    inner: Kalman,
}

/// Releases a Kalman filter handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `kalman` must be a handle from [`pamoja_kalman_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_kalman_free(kalman: *mut PamojaKalman) {
    if !kalman.is_null() {
        drop(Box::from_raw(kalman));
    }
}

/// An opaque handle to a boolean debouncer.
pub struct PamojaDebounce {
    inner: Debounce,
}

/// Releases a debouncer handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `debounce` must be a handle from [`pamoja_debounce_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_debounce_free(debounce: *mut PamojaDebounce) {
    if !debounce.is_null() {
        drop(Box::from_raw(debounce));
    }
}

/// An opaque handle to a rate limiter.
pub struct PamojaRamp {
    inner: Ramp,
}

/// Releases a rate limiter handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `ramp` must be a handle from [`pamoja_ramp_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_ramp_free(ramp: *mut PamojaRamp) {
    if !ramp.is_null() {
        drop(Box::from_raw(ramp));
    }
}

/// An opaque handle to a step-change detector.
pub struct PamojaSurge {
    inner: Surge,
}

/// Releases a surge detector handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `surge` must be a handle from a surge constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_surge_free(surge: *mut PamojaSurge) {
    if !surge.is_null() {
        drop(Box::from_raw(surge));
    }
}

/// An opaque handle to a raw-to-units calibration.
pub struct PamojaCalibration {
    inner: Calibration,
}

/// Releases a calibration handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `calibration` must be a handle from a calibration constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_calibration_free(calibration: *mut PamojaCalibration) {
    if !calibration.is_null() {
        drop(Box::from_raw(calibration));
    }
}

/// An opaque handle to a circular geofence.
pub struct PamojaGeofence {
    inner: Geofence,
}

/// Releases a geofence handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `geofence` must be a handle from [`pamoja_geofence_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_geofence_free(geofence: *mut PamojaGeofence) {
    if !geofence.is_null() {
        drop(Box::from_raw(geofence));
    }
}

/// Creates an exponential smoother.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_smoother_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_smoother_new(weight: f32) -> *mut PamojaSmoother {
    Box::into_raw(Box::new(PamojaSmoother {
        inner: Smoother::new(weight),
    }))
}

/// Folds a sample into a smoother and returns the smoothed value.
///
/// # Returns
///
/// The smoothed value, or NaN if `smoother` is null.
///
/// # Safety
///
/// `smoother` must be a live handle from [`pamoja_smoother_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_smoother_update(smoother: *mut PamojaSmoother, sample: f32) -> f32 {
    match smoother.as_mut() {
        Some(smoother) => smoother.inner.update(sample),
        None => f32::NAN,
    }
}

/// Reads a smoother's current value without folding in a sample.
///
/// # Returns
///
/// `true` if a value is available, having written it to `out_value`; `false` if
/// no sample has been seen yet or `smoother` is null.
///
/// # Safety
///
/// `smoother` must be a live handle from [`pamoja_smoother_new`], or null, and
/// `out_value` must point to a writable `float` or be null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_smoother_value(
    smoother: *const PamojaSmoother,
    out_value: *mut f32,
) -> bool {
    let Some(smoother) = smoother.as_ref() else {
        return false;
    };
    write_some(smoother.inner.value(), out_value)
}

/// Clears a smoother back to its initial state.
///
/// # Safety
///
/// `smoother` must be a live handle from [`pamoja_smoother_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_smoother_reset(smoother: *mut PamojaSmoother) {
    if let Some(smoother) = smoother.as_mut() {
        smoother.inner.reset();
    }
}

/// Creates a PID controller with the given gains and no output limits.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_pid_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_pid_new(kp: f32, ki: f32, kd: f32) -> *mut PamojaPid {
    Box::into_raw(Box::new(PamojaPid {
        inner: Pid::new(kp, ki, kd),
    }))
}

/// Creates a PID controller whose output is clamped to `[min, max]`.
///
/// Either side may be infinite, or NaN, to leave it open; a `max` below `min` is
/// swapped with it.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_pid_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_pid_new_with_limits(
    kp: f32,
    ki: f32,
    kd: f32,
    min: f32,
    max: f32,
) -> *mut PamojaPid {
    Box::into_raw(Box::new(PamojaPid {
        inner: Pid::new(kp, ki, kd).with_limits(min, max),
    }))
}

/// Advances a PID controller by one step.
///
/// `dt` is the time since the previous step, in the unit the integral and derivative
/// gains assume; one at or below zero, or not a finite number, skips the integral and
/// derivative. A setpoint or measurement that is not a finite number is ignored and the
/// previous output returned.
///
/// # Returns
///
/// The control output, or NaN if `pid` is null.
///
/// # Safety
///
/// `pid` must be a live handle from a PID constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_pid_update(
    pid: *mut PamojaPid,
    setpoint: f32,
    measurement: f32,
    dt: f32,
) -> f32 {
    match pid.as_mut() {
        Some(pid) => pid.inner.update(setpoint, measurement, dt),
        None => f32::NAN,
    }
}

/// Clears a PID controller's accumulated integral, its last error, and the output it
/// last returned.
///
/// # Safety
///
/// `pid` must be a live handle from a PID constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_pid_reset(pid: *mut PamojaPid) {
    if let Some(pid) = pid.as_mut() {
        pid.inner.reset();
    }
}

/// Creates a cooling thermostat, which switches on when the reading rises.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_thermostat_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_thermostat_cooling(
    setpoint: f32,
    hysteresis: f32,
) -> *mut PamojaThermostat {
    Box::into_raw(Box::new(PamojaThermostat {
        inner: Thermostat::cooling(setpoint, hysteresis),
    }))
}

/// Creates a heating thermostat, which switches on when the reading falls.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_thermostat_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_thermostat_heating(
    setpoint: f32,
    hysteresis: f32,
) -> *mut PamojaThermostat {
    Box::into_raw(Box::new(PamojaThermostat {
        inner: Thermostat::heating(setpoint, hysteresis),
    }))
}

/// Feeds a reading to a thermostat and returns whether the load should be on.
///
/// # Returns
///
/// `true` while the load should run, or `false` if `thermostat` is null.
///
/// # Safety
///
/// `thermostat` must be a live handle from a thermostat constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_thermostat_update(
    thermostat: *mut PamojaThermostat,
    reading: f32,
) -> bool {
    match thermostat.as_mut() {
        Some(thermostat) => thermostat.inner.update(reading),
        None => false,
    }
}

/// Reports a thermostat's current output without feeding it a reading.
///
/// # Returns
///
/// `true` while the load should run, or `false` if `thermostat` is null.
///
/// # Safety
///
/// `thermostat` must be a live handle from a thermostat constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_thermostat_is_on(thermostat: *const PamojaThermostat) -> bool {
    match thermostat.as_ref() {
        Some(thermostat) => thermostat.inner.is_on(),
        None => false,
    }
}

/// Creates a depletion estimator that warns as a level approaches `threshold`.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_depletion_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_depletion_new(threshold: f32) -> *mut PamojaDepletion {
    Box::into_raw(Box::new(PamojaDepletion {
        inner: Depletion::new(threshold),
    }))
}

/// Records a level and estimates how many samples remain before the threshold.
///
/// # Returns
///
/// `true` if an estimate is available, having written it to `out_samples`: 0 once
/// the level is at or below the threshold, the first reading included. `false` if
/// the level is steady or rising, on a first reading above the threshold, when no
/// rate is known yet, for a level that is not a finite number, or if `depletion`
/// is null.
///
/// # Safety
///
/// `depletion` must be a live handle from [`pamoja_depletion_new`], or null, and
/// `out_samples` must point to a writable `uint32_t` or be null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_depletion_update(
    depletion: *mut PamojaDepletion,
    level: f32,
    out_samples: *mut u32,
) -> bool {
    let Some(depletion) = depletion.as_mut() else {
        return false;
    };
    write_some(depletion.inner.update(level), out_samples)
}

/// Creates a one-dimensional Kalman filter.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_kalman_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_kalman_new(
    process_noise: f32,
    measurement_noise: f32,
    initial: f32,
) -> *mut PamojaKalman {
    Box::into_raw(Box::new(PamojaKalman {
        inner: Kalman::new(process_noise, measurement_noise, initial),
    }))
}

/// Folds a reading into a Kalman filter and returns the new estimate.
///
/// # Returns
///
/// The updated estimate, or NaN if `kalman` is null.
///
/// # Safety
///
/// `kalman` must be a live handle from [`pamoja_kalman_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_kalman_update(kalman: *mut PamojaKalman, reading: f32) -> f32 {
    match kalman.as_mut() {
        Some(kalman) => kalman.inner.update(reading),
        None => f32::NAN,
    }
}

/// Reads a Kalman filter's current estimate without folding in a reading.
///
/// # Returns
///
/// The current estimate, or NaN if `kalman` is null.
///
/// # Safety
///
/// `kalman` must be a live handle from [`pamoja_kalman_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_kalman_estimate(kalman: *const PamojaKalman) -> f32 {
    match kalman.as_ref() {
        Some(kalman) => kalman.inner.estimate(),
        None => f32::NAN,
    }
}

/// Creates a debouncer that requires `samples` agreeing readings to change state.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_debounce_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_debounce_new(samples: u16, initial: bool) -> *mut PamojaDebounce {
    Box::into_raw(Box::new(PamojaDebounce {
        inner: Debounce::new(samples, initial),
    }))
}

/// Feeds a raw reading to a debouncer and returns the settled state.
///
/// # Returns
///
/// The debounced state, or `false` if `debounce` is null.
///
/// # Safety
///
/// `debounce` must be a live handle from [`pamoja_debounce_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_debounce_update(debounce: *mut PamojaDebounce, raw: bool) -> bool {
    match debounce.as_mut() {
        Some(debounce) => debounce.inner.update(raw),
        None => false,
    }
}

/// Reports a debouncer's settled state without feeding it a reading.
///
/// # Returns
///
/// The debounced state, or `false` if `debounce` is null.
///
/// # Safety
///
/// `debounce` must be a live handle from [`pamoja_debounce_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_debounce_state(debounce: *const PamojaDebounce) -> bool {
    match debounce.as_ref() {
        Some(debounce) => debounce.inner.state(),
        None => false,
    }
}

/// Creates a rate limiter starting at `start` and moving at most `max_step`.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_ramp_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_ramp_new(start: f32, max_step: f32) -> *mut PamojaRamp {
    Box::into_raw(Box::new(PamojaRamp {
        inner: Ramp::new(start, max_step),
    }))
}

/// Moves a ramp one step toward `target` and returns the new value.
///
/// # Returns
///
/// The rate-limited value, or NaN if `ramp` is null.
///
/// # Safety
///
/// `ramp` must be a live handle from [`pamoja_ramp_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_ramp_update(ramp: *mut PamojaRamp, target: f32) -> f32 {
    match ramp.as_mut() {
        Some(ramp) => ramp.inner.update(target),
        None => f32::NAN,
    }
}

/// Reads a ramp's current value.
///
/// # Returns
///
/// The current value, or NaN if `ramp` is null.
///
/// # Safety
///
/// `ramp` must be a live handle from [`pamoja_ramp_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_ramp_value(ramp: *const PamojaRamp) -> f32 {
    match ramp.as_ref() {
        Some(ramp) => ramp.inner.value(),
        None => f32::NAN,
    }
}

/// Forces a ramp to a value without rate limiting.
///
/// # Safety
///
/// `ramp` must be a live handle from [`pamoja_ramp_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_ramp_set(ramp: *mut PamojaRamp, value: f32) {
    if let Some(ramp) = ramp.as_mut() {
        ramp.inner.set(value);
    }
}

/// Creates a detector for rises of more than `limit` between readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_surge_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_surge_rising(limit: f32) -> *mut PamojaSurge {
    Box::into_raw(Box::new(PamojaSurge {
        inner: Surge::rising(limit),
    }))
}

/// Creates a detector for falls of more than `limit` between readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_surge_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_surge_falling(limit: f32) -> *mut PamojaSurge {
    Box::into_raw(Box::new(PamojaSurge {
        inner: Surge::falling(limit),
    }))
}

/// Feeds a value to a surge detector.
///
/// # Returns
///
/// `true` if the change since the previous reading went past the limit in the
/// watched direction, having written its size, as a positive number, to `out_delta`;
/// `false` otherwise, on the first reading, or if `surge` is null.
///
/// # Safety
///
/// `surge` must be a live handle from a surge constructor, or null, and
/// `out_delta` must point to a writable `float` or be null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_surge_update(
    surge: *mut PamojaSurge,
    value: f32,
    out_delta: *mut f32,
) -> bool {
    let Some(surge) = surge.as_mut() else {
        return false;
    };
    write_some(surge.inner.update(value), out_delta)
}

/// Creates a calibration applying `raw * scale + offset`.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_calibration_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_calibration_linear(
    scale: f32,
    offset: f32,
) -> *mut PamojaCalibration {
    Box::into_raw(Box::new(PamojaCalibration {
        inner: Calibration::linear(scale, offset),
    }))
}

/// Creates a calibration fitted through two known reference points.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_calibration_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_calibration_two_point(
    raw_low: f32,
    value_low: f32,
    raw_high: f32,
    value_high: f32,
) -> *mut PamojaCalibration {
    Box::into_raw(Box::new(PamojaCalibration {
        inner: Calibration::two_point(raw_low, value_low, raw_high, value_high),
    }))
}

/// Converts a raw reading into calibrated units.
///
/// # Returns
///
/// The calibrated value, or NaN if `calibration` is null.
///
/// # Safety
///
/// `calibration` must be a live handle from a calibration constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_calibration_apply(
    calibration: *const PamojaCalibration,
    raw: f32,
) -> f32 {
    match calibration.as_ref() {
        Some(calibration) => calibration.inner.apply(raw),
        None => f32::NAN,
    }
}

/// Creates a circular geofence of `radius_m` around `center`.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_geofence_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_geofence_new(
    center: PamojaCoordinate,
    radius_m: f64,
) -> *mut PamojaGeofence {
    Box::into_raw(Box::new(PamojaGeofence {
        inner: Geofence::new(center.into(), radius_m),
    }))
}

/// Feeds a fix to a geofence and reports where it sits, including a crossing.
///
/// # Returns
///
/// The boundary state for this fix, or [`PamojaBoundary::Outside`] if `geofence`
/// is null.
///
/// # Safety
///
/// `geofence` must be a live handle from [`pamoja_geofence_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_geofence_update(
    geofence: *mut PamojaGeofence,
    point: PamojaCoordinate,
) -> PamojaBoundary {
    match geofence.as_mut() {
        Some(geofence) => geofence.inner.update(point.into()).into(),
        None => PamojaBoundary::Outside,
    }
}

/// Reports whether a fix lies inside a geofence, without recording a crossing.
///
/// # Returns
///
/// `true` if the fix is inside, or `false` if it is outside or `geofence` is null.
///
/// # Safety
///
/// `geofence` must be a live handle from [`pamoja_geofence_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_geofence_contains(
    geofence: *const PamojaGeofence,
    point: PamojaCoordinate,
) -> bool {
    match geofence.as_ref() {
        Some(geofence) => geofence.inner.contains(point.into()),
        None => false,
    }
}

/// Returns the great-circle distance between two coordinates, in meters.
#[no_mangle]
pub extern "C" fn pamoja_coordinate_distance_to(
    from: PamojaCoordinate,
    to: PamojaCoordinate,
) -> f64 {
    Coordinate::from(from).distance_to(to.into())
}

/// Returns the initial bearing from one coordinate to another, in degrees.
#[no_mangle]
pub extern "C" fn pamoja_coordinate_bearing_to(
    from: PamojaCoordinate,
    to: PamojaCoordinate,
) -> f64 {
    Coordinate::from(from).bearing_to(to.into())
}

/// Holds a reading at `center` while it stays within `width` either side, so small
/// wiggle around a setpoint does not act.
///
/// # Returns
///
/// `center` while `value` is within `width` of it, and otherwise `value` unchanged.
#[no_mangle]
pub extern "C" fn pamoja_kit_deadband(value: f32, center: f32, width: f32) -> f32 {
    deadband(value, center, width)
}

/// An opaque handle to a complementary filter.
pub struct PamojaComplementary {
    inner: Complementary,
}

/// Creates a complementary filter, which fuses a drifting rate with a noisy absolute
/// reading.
///
/// # Arguments
///
/// * `alpha` - the weight on the integrated rate, held to 0 to 1; near 1 trusts the rate and
///   corrects slowly. One that is not a number is taken as 0, following the absolute
///   reading.
/// * `initial` - the starting estimate.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_complementary_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_complementary_new(
    alpha: f32,
    initial: f32,
) -> *mut PamojaComplementary {
    Box::into_raw(Box::new(PamojaComplementary {
        inner: Complementary::new(alpha, initial),
    }))
}

/// Fuses a rate and an absolute reading over a time step.
///
/// If the rate, the absolute reading, or the time step is not a finite number, the update
/// is ignored.
///
/// # Returns
///
/// The fused estimate, or NaN if `filter` is null.
///
/// # Safety
///
/// `filter` must be a live handle from [`pamoja_complementary_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_complementary_update(
    filter: *mut PamojaComplementary,
    rate: f32,
    absolute: f32,
    dt: f32,
) -> f32 {
    match filter.as_mut() {
        Some(filter) => filter.inner.update(rate, absolute, dt),
        None => f32::NAN,
    }
}

/// Reads a complementary filter's estimate.
///
/// # Returns
///
/// The estimate, or NaN if `filter` is null.
///
/// # Safety
///
/// `filter` must be a live handle from [`pamoja_complementary_new`], or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_complementary_estimate(filter: *const PamojaComplementary) -> f32 {
    match filter.as_ref() {
        Some(filter) => filter.inner.estimate(),
        None => f32::NAN,
    }
}

/// Releases a complementary filter handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `filter` must be a handle from [`pamoja_complementary_new`] that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_complementary_free(filter: *mut PamojaComplementary) {
    if !filter.is_null() {
        drop(Box::from_raw(filter));
    }
}

/// Roll and pitch, in degrees.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PamojaTilt {
    /// Rotation about the forward axis, in degrees, from -180 to 180.
    pub roll: f64,
    /// Rotation about the right axis, in degrees, from -90 to 90.
    pub pitch: f64,
}

/// Computes roll and pitch from a three-axis accelerometer at rest.
///
/// # Arguments
///
/// * `ax` - acceleration along the forward axis, in any unit.
/// * `ay` - acceleration along the right axis, in the same unit.
/// * `az` - acceleration along the up axis, in the same unit.
///
/// # Returns
///
/// The tilt in degrees.
#[no_mangle]
pub extern "C" fn pamoja_imu_tilt_from_accel(ax: f64, ay: f64, az: f64) -> PamojaTilt {
    let tilt = imu::tilt_from_accel(ax, ay, az);
    PamojaTilt {
        roll: tilt.roll,
        pitch: tilt.pitch,
    }
}

/// Computes the dew point from the air temperature and relative humidity.
///
/// # Arguments
///
/// * `celsius` - the air temperature, in degrees Celsius.
/// * `humidity_percent` - the relative humidity, in percent; one at or below 0 is taken as
///   a tiny positive value.
///
/// # Returns
///
/// The dew point, in degrees Celsius.
#[no_mangle]
pub extern "C" fn pamoja_weather_dew_point(celsius: f64, humidity_percent: f64) -> f64 {
    weather::dew_point(celsius, humidity_percent)
}

/// Converts degrees Celsius to degrees Fahrenheit.
#[no_mangle]
pub extern "C" fn pamoja_units_celsius_to_fahrenheit(celsius: f32) -> f32 {
    units::celsius_to_fahrenheit(celsius)
}

/// Converts degrees Fahrenheit to degrees Celsius.
#[no_mangle]
pub extern "C" fn pamoja_units_fahrenheit_to_celsius(fahrenheit: f32) -> f32 {
    units::fahrenheit_to_celsius(fahrenheit)
}

/// Converts degrees Celsius to kelvin.
#[no_mangle]
pub extern "C" fn pamoja_units_celsius_to_kelvin(celsius: f32) -> f32 {
    units::celsius_to_kelvin(celsius)
}

/// Converts kelvin to degrees Celsius.
#[no_mangle]
pub extern "C" fn pamoja_units_kelvin_to_celsius(kelvin: f32) -> f32 {
    units::kelvin_to_celsius(kelvin)
}

/// Converts pascals to hectopascals.
#[no_mangle]
pub extern "C" fn pamoja_units_pascals_to_hectopascals(pascals: f32) -> f32 {
    units::pascals_to_hectopascals(pascals)
}

/// Converts hectopascals to pascals.
#[no_mangle]
pub extern "C" fn pamoja_units_hectopascals_to_pascals(hectopascals: f32) -> f32 {
    units::hectopascals_to_pascals(hectopascals)
}

/// Converts pascals to kilopascals.
#[no_mangle]
pub extern "C" fn pamoja_units_pascals_to_kilopascals(pascals: f32) -> f32 {
    units::pascals_to_kilopascals(pascals)
}

/// Converts kilopascals to pascals.
#[no_mangle]
pub extern "C" fn pamoja_units_kilopascals_to_pascals(kilopascals: f32) -> f32 {
    units::kilopascals_to_pascals(kilopascals)
}

/// Converts pascals to pounds per square inch.
#[no_mangle]
pub extern "C" fn pamoja_units_pascals_to_psi(pascals: f32) -> f32 {
    units::pascals_to_psi(pascals)
}

/// Converts pounds per square inch to pascals.
#[no_mangle]
pub extern "C" fn pamoja_units_psi_to_pascals(psi: f32) -> f32 {
    units::psi_to_pascals(psi)
}

/// Converts a ratio from 0 to 1 to a percentage.
#[no_mangle]
pub extern "C" fn pamoja_units_ratio_to_percent(ratio: f32) -> f32 {
    units::ratio_to_percent(ratio)
}

/// Converts a percentage to a ratio from 0 to 1.
#[no_mangle]
pub extern "C" fn pamoja_units_percent_to_ratio(percent: f32) -> f32 {
    units::percent_to_ratio(percent)
}

/// Writes an optional value through an out-pointer, reporting whether it was set.
///
/// # Safety
///
/// `out` must point to a writable `T`, or be null.
unsafe fn write_some<T>(value: Option<T>, out: *mut T) -> bool {
    match value {
        Some(value) => {
            if !out.is_null() {
                ptr::write(out, value);
            }
            true
        }
        None => false,
    }
}

/// The most readings a windowed helper keeps, and the number it keeps unless told
/// fewer.
///
/// The Rust helpers are generic over their capacity, which cannot cross a C ABI,
/// so the ones here are built with room for this many; each has a `_with_capacity`
/// constructor that keeps fewer.
pub const PAMOJA_WINDOW_CAPACITY: usize = 32;

/// Checks a capacity asked of a windowed helper: from `least`, the fewest readings the
/// helper can answer from, up to [`PAMOJA_WINDOW_CAPACITY`].
fn fits(capacity: usize, least: usize) -> bool {
    (least..=PAMOJA_WINDOW_CAPACITY).contains(&capacity)
}

/// An opaque handle to a rolling window of readings.
pub struct PamojaWindow {
    inner: Window<PAMOJA_WINDOW_CAPACITY>,
}

/// An opaque handle to a median filter.
pub struct PamojaMedian {
    inner: Median<PAMOJA_WINDOW_CAPACITY>,
}

/// An opaque handle to a trend estimator.
pub struct PamojaTrend {
    inner: Trend<PAMOJA_WINDOW_CAPACITY>,
}

/// An opaque handle to an anomaly detector.
pub struct PamojaAnomaly {
    inner: Anomaly<PAMOJA_WINDOW_CAPACITY>,
}

/// Creates an empty rolling window of [`PAMOJA_WINDOW_CAPACITY`] readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_window_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_new() -> *mut PamojaWindow {
    Box::into_raw(Box::new(PamojaWindow {
        inner: Window::new(),
    }))
}

/// Creates an empty rolling window that keeps up to `capacity` readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_window_free`], or null if
/// `capacity` is not from 1 to [`PAMOJA_WINDOW_CAPACITY`].
///
/// # Safety
///
/// A returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_with_capacity(capacity: usize) -> *mut PamojaWindow {
    if !fits(capacity, 1) {
        return ptr::null_mut();
    }
    Box::into_raw(Box::new(PamojaWindow {
        inner: Window::with_capacity(capacity),
    }))
}

/// Adds a reading, dropping the oldest once the window is full.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `window` must be a live handle from a window constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_push(window: *mut PamojaWindow, reading: f32) {
    if let Some(window) = window.as_mut() {
        window.inner.push(reading);
    }
}

/// Returns how many readings a window holds.
///
/// # Returns
///
/// The count, or 0 if `window` is null.
///
/// # Safety
///
/// `window` must be a live handle from a window constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_len(window: *const PamojaWindow) -> usize {
    match window.as_ref() {
        Some(window) => window.inner.len(),
        None => 0,
    }
}

/// Returns how many readings a window holds before it starts dropping.
///
/// # Returns
///
/// The capacity, or 0 if `window` is null.
///
/// # Safety
///
/// `window` must be a live handle from a window constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_capacity(window: *const PamojaWindow) -> usize {
    match window.as_ref() {
        Some(window) => window.inner.capacity(),
        None => 0,
    }
}

/// Reports whether a window holds as many readings as it keeps.
///
/// # Returns
///
/// `true` once the window is full, or `false` before that or if `window` is null.
///
/// # Safety
///
/// `window` must be a live handle from a window constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_is_full(window: *const PamojaWindow) -> bool {
    match window.as_ref() {
        Some(window) => window.inner.is_full(),
        None => false,
    }
}

/// Reads the most recent reading in a window.
///
/// # Returns
///
/// `true` when the window holds a reading, with it written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_latest(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.latest()),
        out_value,
    )
}

/// Reads the oldest reading a window still holds.
///
/// # Returns
///
/// `true` when the window holds a reading, with it written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_oldest(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.oldest()),
        out_value,
    )
}

/// Reads the mean of a window's readings.
///
/// # Returns
///
/// `true` when the window holds a reading, with the mean written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_mean(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.mean()),
        out_value,
    )
}

/// Reads the smallest reading in a window.
///
/// # Returns
///
/// `true` when the window holds a reading, with the value written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_min(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.min()),
        out_value,
    )
}

/// Reads the largest reading in a window.
///
/// # Returns
///
/// `true` when the window holds a reading, with the value written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_max(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.max()),
        out_value,
    )
}

/// Reads the spread between a window's smallest and largest readings.
///
/// # Returns
///
/// `true` when the window holds a reading, with the range written to `out_value`.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_range(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.range()),
        out_value,
    )
}

/// Reads the population variance of a window's readings.
///
/// # Returns
///
/// `true` when the window holds a reading, with the variance written to
/// `out_value`; one reading has a variance of 0.
///
/// # Safety
///
/// `window` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_variance(
    window: *const PamojaWindow,
    out_value: *mut f32,
) -> bool {
    maybe(
        window.as_ref().and_then(|window| window.inner.variance()),
        out_value,
    )
}

/// Releases a rolling window handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `window` must be a handle from a window constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_window_free(window: *mut PamojaWindow) {
    if !window.is_null() {
        drop(Box::from_raw(window));
    }
}

/// Creates an empty median filter over [`PAMOJA_WINDOW_CAPACITY`] readings.
///
/// A median filter is what rejects a single wild reading, where an average would
/// let it pull the answer.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_median_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_new() -> *mut PamojaMedian {
    Box::into_raw(Box::new(PamojaMedian {
        inner: Median::new(),
    }))
}

/// Creates an empty median filter over up to `capacity` readings.
///
/// A small odd window, such as 5, follows a real change in a few readings; a window
/// of 32 follows it 16 readings late.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_median_free`], or null if
/// `capacity` is not from 1 to [`PAMOJA_WINDOW_CAPACITY`].
///
/// # Safety
///
/// A returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_with_capacity(capacity: usize) -> *mut PamojaMedian {
    if !fits(capacity, 1) {
        return ptr::null_mut();
    }
    Box::into_raw(Box::new(PamojaMedian {
        inner: Median::with_capacity(capacity),
    }))
}

/// Returns how many readings a median filter keeps.
///
/// # Returns
///
/// The capacity, or 0 if `median` is null.
///
/// # Safety
///
/// `median` must be a live handle from a median constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_capacity(median: *const PamojaMedian) -> usize {
    match median.as_ref() {
        Some(median) => median.inner.capacity(),
        None => 0,
    }
}

/// Folds a reading in and returns the median of the window.
///
/// # Returns
///
/// The median, or NaN if `median` is null.
///
/// # Safety
///
/// `median` must be a live handle from a median constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_update(median: *mut PamojaMedian, reading: f32) -> f32 {
    match median.as_mut() {
        Some(median) => median.inner.update(reading),
        None => f32::NAN,
    }
}

/// Reads the current median without folding in a reading.
///
/// # Returns
///
/// `true` when the filter holds a reading, with the median written to
/// `out_value`.
///
/// # Safety
///
/// `median` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_value(
    median: *const PamojaMedian,
    out_value: *mut f32,
) -> bool {
    maybe(
        median.as_ref().and_then(|median| median.inner.median()),
        out_value,
    )
}

/// Releases a median filter handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `median` must be a handle from a median constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_median_free(median: *mut PamojaMedian) {
    if !median.is_null() {
        drop(Box::from_raw(median));
    }
}

/// Creates an empty trend estimator over [`PAMOJA_WINDOW_CAPACITY`] readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_trend_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_new() -> *mut PamojaTrend {
    Box::into_raw(Box::new(PamojaTrend {
        inner: Trend::new(),
    }))
}

/// Creates an empty trend estimator over up to `capacity` readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_trend_free`], or null if
/// `capacity` is not from 2 to [`PAMOJA_WINDOW_CAPACITY`], since a line needs two
/// readings.
///
/// # Safety
///
/// A returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_with_capacity(capacity: usize) -> *mut PamojaTrend {
    if !fits(capacity, 2) {
        return ptr::null_mut();
    }
    Box::into_raw(Box::new(PamojaTrend {
        inner: Trend::with_capacity(capacity),
    }))
}

/// Returns how many readings a trend estimator keeps.
///
/// # Returns
///
/// The capacity, or 0 if `trend` is null.
///
/// # Safety
///
/// `trend` must be a live handle from a trend constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_capacity(trend: *const PamojaTrend) -> usize {
    match trend.as_ref() {
        Some(trend) => trend.inner.capacity(),
        None => 0,
    }
}

/// Adds a reading to a trend estimator.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `trend` must be a live handle from a trend constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_push(trend: *mut PamojaTrend, reading: f32) {
    if let Some(trend) = trend.as_mut() {
        trend.inner.push(reading);
    }
}

/// Reads the slope a trend estimator has fitted, in units per reading.
///
/// # Returns
///
/// `true` once it holds two readings, with the slope written to `out_value`. A
/// positive slope is a rising signal.
///
/// # Safety
///
/// `trend` must be a live handle or null, and `out_value` must point to a
/// writable `float`.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_slope(
    trend: *const PamojaTrend,
    out_value: *mut f32,
) -> bool {
    maybe(
        trend.as_ref().and_then(|trend| trend.inner.slope()),
        out_value,
    )
}

/// Releases a trend estimator handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `trend` must be a handle from a trend constructor that has not already been
/// freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_trend_free(trend: *mut PamojaTrend) {
    if !trend.is_null() {
        drop(Box::from_raw(trend));
    }
}

/// Creates an anomaly detector that flags a reading `sigmas` deviations out.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_anomaly_free`].
///
/// # Safety
///
/// The returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_anomaly_new(sigmas: f32) -> *mut PamojaAnomaly {
    Box::into_raw(Box::new(PamojaAnomaly {
        inner: Anomaly::new(sigmas),
    }))
}

/// Creates an anomaly detector whose baseline keeps up to `capacity` readings.
///
/// # Returns
///
/// A handle the caller must release with [`pamoja_anomaly_free`], or null if
/// `capacity` is not from 2 to [`PAMOJA_WINDOW_CAPACITY`], since a spread needs two
/// readings.
///
/// # Safety
///
/// A returned handle must be freed exactly once.
#[no_mangle]
pub unsafe extern "C" fn pamoja_anomaly_with_capacity(
    sigmas: f32,
    capacity: usize,
) -> *mut PamojaAnomaly {
    if !fits(capacity, 2) {
        return ptr::null_mut();
    }
    Box::into_raw(Box::new(PamojaAnomaly {
        inner: Anomaly::with_capacity(sigmas, capacity),
    }))
}

/// Returns how many readings an anomaly detector's baseline keeps.
///
/// # Returns
///
/// The capacity, or 0 if `anomaly` is null.
///
/// # Safety
///
/// `anomaly` must be a live handle from an anomaly constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_anomaly_capacity(anomaly: *const PamojaAnomaly) -> usize {
    match anomaly.as_ref() {
        Some(anomaly) => anomaly.inner.capacity(),
        None => 0,
    }
}

/// Folds a reading in and reports whether it stands out from the readings before it.
///
/// # Returns
///
/// `true` when the reading is further from the mean than the configured number
/// of deviations, or is not a finite number. `false` otherwise, before two readings
/// are held, or if `anomaly` is null.
///
/// # Safety
///
/// `anomaly` must be a live handle from an anomaly constructor, or null.
#[no_mangle]
pub unsafe extern "C" fn pamoja_anomaly_check(anomaly: *mut PamojaAnomaly, reading: f32) -> bool {
    match anomaly.as_mut() {
        Some(anomaly) => anomaly.inner.check(reading),
        None => false,
    }
}

/// Releases an anomaly detector handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `anomaly` must be a handle from an anomaly constructor that has not already
/// been freed, or null. After this call it must not be used again.
#[no_mangle]
pub unsafe extern "C" fn pamoja_anomaly_free(anomaly: *mut PamojaAnomaly) {
    if !anomaly.is_null() {
        drop(Box::from_raw(anomaly));
    }
}

/// Writes an optional value through an out-pointer, reporting whether there was one.
///
/// # Safety
///
/// `out_value` must be null or point to a writable `float`.
unsafe fn maybe(value: Option<f32>, out_value: *mut f32) -> bool {
    match (value, out_value.as_mut()) {
        (Some(value), Some(slot)) => {
            *slot = value;
            true
        }
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_smoother_converges_toward_the_signal() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let smoother = pamoja_smoother_new(0.5);
            assert_eq!(pamoja_smoother_update(smoother, 10.0), 10.0);
            let second = pamoja_smoother_update(smoother, 20.0);
            assert!(second > 10.0 && second < 20.0);

            let mut value = 0.0f32;
            assert!(pamoja_smoother_value(smoother, &mut value));
            assert_eq!(value, second);

            pamoja_smoother_reset(smoother);
            assert!(!pamoja_smoother_value(smoother, &mut value));
            pamoja_smoother_free(smoother);
        }
    }

    #[test]
    fn a_cooling_thermostat_switches_on_above_its_setpoint() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let thermostat = pamoja_thermostat_cooling(8.0, 1.0);
            assert!(!pamoja_thermostat_update(thermostat, 7.0));
            assert!(pamoja_thermostat_update(thermostat, 9.5));
            assert!(pamoja_thermostat_is_on(thermostat));
            pamoja_thermostat_free(thermostat);

            let trigger = pamoja_trigger_below(30.0, 5.0);
            assert_eq!(pamoja_trigger_update(trigger, 42.0), PamojaEdge::None);
            assert_eq!(pamoja_trigger_update(trigger, 28.0), PamojaEdge::Set);
            assert!(pamoja_trigger_is_set(trigger));
            assert_eq!(pamoja_trigger_update(trigger, 33.0), PamojaEdge::None);
            assert_eq!(pamoja_trigger_update(trigger, 36.0), PamojaEdge::Cleared);
            assert!(!pamoja_trigger_is_set(trigger));
            assert_eq!(
                pamoja_trigger_update(ptr::null_mut(), 1.0),
                PamojaEdge::None
            );
            pamoja_trigger_free(trigger);
        }
    }

    #[test]
    fn a_depletion_estimate_appears_once_a_fall_is_measured() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let depletion = pamoja_depletion_new(10.0);
            let mut samples = 0u32;
            // The first reading establishes no rate, so there is nothing to report.
            assert!(!pamoja_depletion_update(depletion, 100.0, &mut samples));
            assert!(pamoja_depletion_update(depletion, 90.0, &mut samples));
            assert!(samples > 0);
            pamoja_depletion_free(depletion);
        }
    }

    #[test]
    fn a_geofence_reports_the_single_crossing_fix() {
        let center = PamojaCoordinate {
            latitude: -1.2921,
            longitude: 36.8219,
        };
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let fence = pamoja_geofence_new(center, 50.0);
            assert_eq!(
                pamoja_geofence_update(fence, center),
                PamojaBoundary::Inside
            );
            let away = PamojaCoordinate {
                latitude: -1.2930,
                longitude: 36.8219,
            };
            assert_eq!(pamoja_geofence_update(fence, away), PamojaBoundary::Exited);
            assert_eq!(pamoja_geofence_update(fence, away), PamojaBoundary::Outside);
            assert!(!pamoja_geofence_contains(fence, away));
            pamoja_geofence_free(fence);
        }
    }

    #[test]
    fn a_two_point_calibration_maps_its_reference_points() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let calibration = pamoja_calibration_two_point(0.0, 0.0, 1024.0, 100.0);
            assert!((pamoja_calibration_apply(calibration, 512.0) - 50.0).abs() < 0.01);
            pamoja_calibration_free(calibration);
        }
    }

    #[test]
    fn a_deadband_holds_the_center_inside_the_band() {
        assert_eq!(pamoja_kit_deadband(0.2, 0.0, 0.5), 0.0);
        assert!(pamoja_kit_deadband(1.0, 0.0, 0.5) > 0.0);
    }

    #[test]
    fn calls_on_null_handles_are_rejected_without_dereferencing() {
        // Safety: every entry point tolerates a null handle.
        unsafe {
            assert!(pamoja_smoother_update(ptr::null_mut(), 1.0).is_nan());
            assert!(!pamoja_thermostat_update(ptr::null_mut(), 1.0));
            assert!(!pamoja_depletion_update(
                ptr::null_mut(),
                1.0,
                ptr::null_mut()
            ));
            assert!(pamoja_calibration_apply(ptr::null(), 1.0).is_nan());
            assert_eq!(
                pamoja_geofence_update(
                    ptr::null_mut(),
                    PamojaCoordinate {
                        latitude: 0.0,
                        longitude: 0.0,
                    }
                ),
                PamojaBoundary::Outside
            );
            // Freeing null is a documented no-op.
            pamoja_smoother_free(ptr::null_mut());
        }
    }

    #[test]
    fn a_surge_reports_the_step_that_crosses_its_limit() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let surge = pamoja_surge_rising(5.0);
            let mut delta = 0.0f32;
            assert!(!pamoja_surge_update(surge, 10.0, &mut delta));
            assert!(!pamoja_surge_update(surge, 12.0, &mut delta));
            assert!(pamoja_surge_update(surge, 20.0, &mut delta));
            assert!(delta >= 5.0);
            pamoja_surge_free(surge);
        }
    }

    #[test]
    fn a_window_reports_its_spread_once_it_holds_a_reading() {
        // Safety: the handle is live and the out-pointer is writable.
        unsafe {
            let window = pamoja_window_new();
            let mut value = 0.0f32;
            assert!(!pamoja_window_mean(window, &mut value), "empty has no mean");

            for reading in [10.0f32, 20.0, 30.0] {
                pamoja_window_push(window, reading);
            }
            assert_eq!(pamoja_window_len(window), 3);
            assert_eq!(pamoja_window_capacity(window), PAMOJA_WINDOW_CAPACITY);
            assert!(pamoja_window_mean(window, &mut value));
            assert!((value - 20.0).abs() < 1e-6);
            assert!(pamoja_window_min(window, &mut value) && (value - 10.0).abs() < 1e-6);
            assert!(pamoja_window_max(window, &mut value) && (value - 30.0).abs() < 1e-6);
            assert!(pamoja_window_range(window, &mut value) && (value - 20.0).abs() < 1e-6);
            assert!(pamoja_window_variance(window, &mut value));
            pamoja_window_free(window);
        }
    }

    #[test]
    fn a_window_drops_its_oldest_reading_once_full() {
        // Safety: the handle is live and the out-pointer is writable.
        unsafe {
            let window = pamoja_window_new();
            for index in 0..PAMOJA_WINDOW_CAPACITY + 8 {
                pamoja_window_push(window, index as f32);
            }
            assert_eq!(pamoja_window_len(window), PAMOJA_WINDOW_CAPACITY);
            let mut value = 0.0f32;
            assert!(pamoja_window_min(window, &mut value));
            assert!((value - 8.0).abs() < 1e-6, "the first eight fell out");
            pamoja_window_free(window);
        }
    }

    #[test]
    fn a_median_rejects_the_single_wild_reading_an_average_would_follow() {
        // Safety: the handle is live.
        unsafe {
            let median = pamoja_median_new();
            for reading in [20.0f32, 21.0, 20.5] {
                pamoja_median_update(median, reading);
            }
            let spike = pamoja_median_update(median, 900.0);
            assert!(spike < 30.0, "the spike does not carry the median: {spike}");
            pamoja_median_free(median);
        }
    }

    #[test]
    fn a_trend_reports_a_rising_signal_as_a_positive_slope() {
        // Safety: the handle is live and the out-pointer is writable.
        unsafe {
            let trend = pamoja_trend_new();
            let mut slope = 0.0f32;
            assert!(
                !pamoja_trend_slope(trend, &mut slope),
                "one point is no line"
            );

            for reading in [1.0f32, 2.0, 3.0, 4.0] {
                pamoja_trend_push(trend, reading);
            }
            assert!(pamoja_trend_slope(trend, &mut slope));
            assert!((slope - 1.0).abs() < 1e-5, "got {slope}");
            pamoja_trend_free(trend);
        }
    }

    #[test]
    fn an_anomaly_detector_flags_the_reading_that_stands_out() {
        // Safety: the handle is live.
        unsafe {
            let anomaly = pamoja_anomaly_new(3.0);
            for _ in 0..8 {
                assert!(!pamoja_anomaly_check(anomaly, 20.0));
            }
            assert!(pamoja_anomaly_check(anomaly, 900.0), "a step that far out");
            pamoja_anomaly_free(anomaly);
        }
    }

    #[test]
    fn a_windowed_helper_keeps_the_capacity_it_is_given_and_refuses_one_it_cannot() {
        // Safety: each handle is checked for null before use and freed once.
        unsafe {
            assert!(pamoja_window_with_capacity(0).is_null());
            assert!(pamoja_window_with_capacity(PAMOJA_WINDOW_CAPACITY + 1).is_null());
            assert!(pamoja_median_with_capacity(0).is_null());
            assert!(
                pamoja_trend_with_capacity(1).is_null(),
                "a line needs two readings"
            );
            assert!(
                pamoja_anomaly_with_capacity(3.0, 1).is_null(),
                "and so does a spread"
            );

            let window = pamoja_window_with_capacity(2);
            assert!(!window.is_null());
            let mut value = 0.0f32;
            assert!(
                !pamoja_window_latest(window, &mut value),
                "empty has no latest"
            );
            for reading in [1.0f32, 2.0, 3.0] {
                pamoja_window_push(window, reading);
            }
            assert!(pamoja_window_is_full(window));
            assert_eq!(pamoja_window_capacity(window), 2);
            assert!(pamoja_window_oldest(window, &mut value) && value == 2.0);
            assert!(pamoja_window_latest(window, &mut value) && value == 3.0);
            pamoja_window_push(window, f32::NAN);
            assert!(pamoja_window_mean(window, &mut value) && value == 2.5);
            pamoja_window_free(window);

            let median = pamoja_median_with_capacity(3);
            assert_eq!(pamoja_median_capacity(median), 3);
            pamoja_median_free(median);
            let trend = pamoja_trend_with_capacity(4);
            assert_eq!(pamoja_trend_capacity(trend), 4);
            pamoja_trend_free(trend);
            let anomaly = pamoja_anomaly_with_capacity(3.0, 8);
            assert_eq!(pamoja_anomaly_capacity(anomaly), 8);
            assert!(pamoja_anomaly_check(anomaly, f32::NAN), "a NaN is flagged");
            pamoja_anomaly_free(anomaly);
        }
    }

    #[test]
    fn the_unit_tilt_and_dew_point_helpers_convert() {
        assert_eq!(pamoja_units_celsius_to_fahrenheit(100.0), 212.0);
        assert_eq!(pamoja_units_fahrenheit_to_celsius(32.0), 0.0);
        assert!((pamoja_units_celsius_to_kelvin(0.0) - 273.15).abs() < 1e-4);
        assert_eq!(pamoja_units_pascals_to_hectopascals(101_325.0), 1013.25);
        assert!((pamoja_units_psi_to_pascals(1.0) - 6894.757).abs() < 1e-2);
        assert_eq!(pamoja_units_ratio_to_percent(0.25), 25.0);
        let rolled = pamoja_imu_tilt_from_accel(0.0, 1.0, 1.0);
        assert!((rolled.roll - 45.0).abs() < 1e-9 && rolled.pitch.abs() < 1e-9);
        assert!((pamoja_weather_dew_point(15.0, 100.0) - 15.0).abs() < 1e-6);
        assert!((pamoja_weather_dew_point(20.0, 50.0) - 9.3).abs() < 0.2);
    }

    #[test]
    fn a_complementary_filter_ignores_a_reading_it_cannot_use() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let tilt = pamoja_complementary_new(0.98, 0.0);
            let settled = pamoja_complementary_update(tilt, 10.0, 1.0, 0.1);
            assert!((settled - 1.0).abs() < 0.05);
            assert_eq!(
                pamoja_complementary_update(tilt, f32::NAN, 1.0, 0.1),
                settled
            );
            assert_eq!(pamoja_complementary_estimate(tilt), settled);
            pamoja_complementary_free(tilt);
            assert!(pamoja_complementary_estimate(ptr::null()).is_nan());
        }
    }

    #[test]
    fn a_trigger_reports_the_line_it_was_given() {
        // Safety: the handle is live for the whole test and freed once at the end.
        unsafe {
            let trigger = pamoja_trigger_above(80.0, -2.0);
            assert_eq!(pamoja_trigger_threshold(trigger), 80.0);
            assert_eq!(pamoja_trigger_hysteresis(trigger), 2.0, "as a magnitude");
            assert!(pamoja_trigger_watches_above(trigger));
            assert_eq!(pamoja_trigger_update(trigger, f32::NAN), PamojaEdge::None);
            pamoja_trigger_free(trigger);
            assert!(pamoja_trigger_threshold(ptr::null()).is_nan());
            assert!(!pamoja_trigger_watches_above(ptr::null()));
        }
    }

    #[test]
    fn calls_on_null_windowed_handles_are_rejected_without_dereferencing() {
        let mut value = 0.0f32;
        // Safety: passing null is explicitly handled.
        unsafe {
            assert_eq!(pamoja_window_len(ptr::null()), 0);
            assert!(!pamoja_window_mean(ptr::null(), &mut value));
            assert!(pamoja_median_update(ptr::null_mut(), 1.0).is_nan());
            assert!(!pamoja_trend_slope(ptr::null(), &mut value));
            assert!(!pamoja_anomaly_check(ptr::null_mut(), 1.0));
            pamoja_window_free(ptr::null_mut());
            pamoja_median_free(ptr::null_mut());
            pamoja_trend_free(ptr::null_mut());
            pamoja_anomaly_free(ptr::null_mut());
        }
    }
}