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 constructor returns null only when allocation is refused,
//! and whose methods document what they return for a null handle, following
//! `pamoja_mqtt_client_is_connected`.
//! Helpers that answer "maybe" return a `bool` and write the value through an
//! out-parameter.

use std::ptr;

use pamoja_kit::{
    deadband, Anomaly, Boundary, Calibration, Coordinate, Debounce, Depletion, Geofence, Kalman,
    Median, Pid, Ramp, Smoother, Surge, Thermostat, Trend, 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 [`pamoja_pid_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_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,
}

/// Releases a thermostat handle.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `thermostat` must be a handle from [`pamoja_thermostat_cooling`] 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 [`pamoja_surge_rising`] 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 [`pamoja_calibration_linear`] 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]`.
///
/// # 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.
///
/// # 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 and last error.
///
/// # 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`;
/// `false` if the level is steady or rising, if no rate is known yet, 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 at least `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 at least `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 this reading completed a qualifying step, having written the size of
/// the step to `out_delta`; `false` otherwise 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 metres.
#[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())
}

/// Suppresses movement within `width` of `center`, so noise does not act.
///
/// # Returns
///
/// `center` while `value` is inside the band, and otherwise `value` shifted
/// toward `center` by half the band width, so the output is continuous.
#[no_mangle]
pub extern "C" fn pamoja_kit_deadband(value: f32, center: f32, width: f32) -> f32 {
    deadband(value, center, width)
}

/// 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 number of readings a windowed helper keeps.
///
/// The Rust helpers are generic over their capacity, which cannot cross a C ABI,
/// so the ones here are built at one documented size. The crate's own examples
/// use three to eight readings, so this is headroom rather than a constraint; a
/// caller who needs another size has the Rust crate.
pub const PAMOJA_WINDOW_CAPACITY: usize = 32;

/// 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(),
    }))
}

/// 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 [`pamoja_window_new`], 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 [`pamoja_window_new`], 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 [`pamoja_window_new`], 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,
    }
}

/// 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 variance of a window's readings.
///
/// # Returns
///
/// `true` when the window holds enough readings to have a variance, 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_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 [`pamoja_window_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_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(),
    }))
}

/// 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 [`pamoja_median_new`], 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 [`pamoja_median_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_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(),
    }))
}

/// Adds a reading to a trend estimator.
///
/// Passing null is a no-op.
///
/// # Safety
///
/// `trend` must be a live handle from [`pamoja_trend_new`], 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` when there are enough readings to fit a line, 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 [`pamoja_trend_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_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),
    }))
}

/// Folds a reading in and reports whether it stands out from the window.
///
/// # Returns
///
/// `true` when the reading is further from the mean than the configured number
/// of deviations, or `false` if `anomaly` is null or the window is still filling.
///
/// # Safety
///
/// `anomaly` must be a live handle from [`pamoja_anomaly_new`], 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 [`pamoja_anomaly_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_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);
        }
    }

    #[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 centre = 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(centre, 50.0);
            assert_eq!(
                pamoja_geofence_update(fence, centre),
                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_centre_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 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());
        }
    }
}