connections 0.1.0

//! Connections among **`fixed`-crate Q-format types** — the
//! `FixedI<N><Frac>` / `FixedU<N><Frac>` wrappers and their
//! cross-crate isomorphisms to the matching std primitive integers.
//! The `core`/`fixed` split between [`crate::core`] and this module
//! is the crate's only top-level domain distinction: every Conn whose
//! endpoints all ship in `core`/`std` lives in [`crate::core`]; every
//! Conn where at least one endpoint is a `fixed`-crate Q-format
//! wrapper lives here.
//!
//! [`fixed`]: https://docs.rs/fixed
//!
//! ## Submodules
//!
//! - [`mod@i008`] / [`mod@i016`] / [`mod@i032`] / [`mod@i064`] / [`mod@i128`] —
//!   signed `FixedI<N><Frac>` Q-format Conns, plus the cross-crate iso
//!   to the matching std integer (`Q000I008` etc.) and the
//!   float-bridge Conns (`F032Q*` / `F064Q*`).
//! - [`mod@u008`] / [`mod@u016`] / [`mod@u032`] / [`mod@u064`] / [`mod@u128`] —
//!   unsigned `FixedU<N><Frac>` Q-format Conns plus their cross-crate
//!   isos and float bridges.
//!
//! ## Example
//!
//! ```rust
//! use connections::core::u032::U032I032;
//!
//! // u32 PID into i32 — saturates instead of wrapping for large values.
//! assert_eq!(U032I032.floor(1_u32), 1_i32);
//! assert_eq!(U032I032.floor((i32::MAX as u32) + 1), i32::MAX);
//! assert_eq!(U032I032.floor(u32::MAX), i32::MAX);
//! ```
//!
//! ## Conn-name prefix conventions
//!
//! Within this module, the `Q` prefix denotes a `FixedI<N>` /
//! `FixedU<N>` Q-format side; sign is implicit from the module path
//! (`fixed::i008` → signed 8-bit, `fixed::u008` → unsigned 8-bit) and
//! the 3-digit field is the frac bit count. Cross-crate Q.0 isos to
//! the matching std primitive use the `Q000I###` / `Q000U###` shape;
//! signed normalized bit isos use `Q<bits-1>I<bits>` (for example
//! `Q015I016` for Q1.15 over `i16` storage).
//! Float-bridge Conns use the `F032Q###` / `F064Q###` (and `F016Q###`
//! gated on the `f16` feature) shapes, with the float side living on
//! the left.
//!
//! Cross-module name collisions (e.g. `Q008Q004` in both
//! [`mod@i008`] and [`mod@u008`]) are allowed and resolved by qualified
//! import.
//!
//! ## Per-host type aliases
//!
//! Each `fixed::iN` / `fixed::uN` submodule exposes `pub type` aliases
//! for its host `FixedI<N>` / `FixedU<N>` at every supported frac level —
//! for example `fixed::i008::I004 = FixedI8<U4>` (signed Q4.4) and
//! `fixed::u016::U008 = FixedU16<U8>` (unsigned Q8.8). The prefix letter
//! (`I`/`U`) marks the host's signedness; the three digits are the
//! **frac level** (≤ the module's host bit-width).
//!
//! This per-host alias layer is deliberately distinct from the
//! [crate-level Conn-name convention](crate#naming), where `I###`/`U###`
//! are reserved for std-primitive sides of a Conn and `Q###` denotes a
//! Q-format wrapper side. The two namespaces never collide: per-host
//! aliases are only reachable via qualified module paths
//! (`connections::fixed::i008::I004`), while Conn-name sides only
//! appear inside 8-char Conn const identifiers such as `Q008Q004`.
//!
//! Aliases stay buried in their host submodule; users qualify the path
//! when reaching for them rather than relying on a crate-root prelude.
//!
//! ## Macros
//!
//! The intra-`fixed`-crate Conns are generated by per-primitive
//! `fix_fix_iN!` / `fix_fix_uN!` macros, each defined locally in its
//! per-host-type submodule (`fixed/i008.rs` etc.).
//!
//! The float-to-Q-format bridge macros (`float_fixed!` /
//! `float_fixed_l!`) and their `__float_fix_*_body!` helpers live in
//! this parent module — they reach into both `crate::float`
//! (`N5<T>`, `BitsToF64Rd`, `RoundDownFromF64`) and the
//! `fixed`-crate Q-format types, so they belong on this side of the
//! `core`/`fixed` split.
//!
//! The std-int Conn macros (`ext_int!`, `int_uint!`, `nz_int_ext!`,
//! …) live in [`crate::core`]; per-host-type submodules import them
//! via `use crate::core::{…}` directly.
//!
//! The `fixed`-crate `FixedI<N><F>` / `FixedU<N><F>` types already
//! derive `PartialEq` / `Eq` / `PartialOrd` / `Ord` upstream —
//! totally ordered by their underlying integer bits — so they flow
//! through any `T: Eq + PartialOrd` law predicate without per-crate
//! impls.

// ── Float → Q-format Conn macros ───────────────────────────────────
//
// `float_fixed!` / `float_fixed_l!` parallel `float_ext_int!` /
// `float_ext_int_l!` from `src/float.rs` but target a `fixed`-crate
// `FixedI<host>`/`FixedU<host>` Q-format wrapper instead of a std
// integer. Live here rather than `src/float.rs` because the macro
// body reaches into `fixed::FixedI*`/`FixedU*` types — hosting them
// next to `ext_int!` keeps the fixed-crate dependency on this side.
//
// Saturation policy mirrors `__float_ext_int_*_body!`:
//
// - `N5(NaN)`          → `PosInf` (ceil) / `NegInf` (floor)
// - `N5(NEG_INFINITY)` → `NegInf`
// - `N5(INFINITY)`     → `PosInf`
// - `N5(v)` with `v >  max_v_f64` → `PosInf` (ceil) / `Finite(MAX)` (floor)
// - `N5(v)` with `v <  min_v_f64` → `Finite(MIN)` (ceil) / `NegInf` (floor)
// - in-range `v`                      → `Finite(<$Fixed<$Frac>>::from_bits((v * 2^F).ceil() as $Bits))`
//                                      / same with `floor()`
//
// `inner` always materialises a finite float for `Finite(q)` and
// emits IEEE infinities for `NegInf`/`PosInf`. The
// round-toward-negative-infinity semantics (via the
// `RoundDownFromF64` dispatch) are L-Galois-correct — round-to-
// nearest-even can over-round and break `ceil(inner(b)) ≤ b`.
//
// All math goes through f64 even for f32/f16 sources: the upcast
// `f as f64` is exact, `2^F` is f64-exact for `F ≤ 1023` (well
// above our `F ≤ 128` rung cadence), and routing through f64
// sidesteps the f32 `2^128` overflow.

// `#[macro_export]` is mandatory even though the macro is internal:
// the public-facing `float_fixed_l!` / `float_fixed_r!` macros — used
// in this crate's own `src/fixed/{i,u}NNN.rs` files even when the
// `macros` cargo feature is off — expand into `$crate::__float_fix_*_body!`
// invocations, which only resolve when the helper sits at the crate
// root. The `__` prefix and `#[doc(hidden)]` mark it as not part of the
// public surface; downstream callers should never invoke it directly.
#[doc(hidden)]
#[macro_export]
macro_rules! __float_fix_ceil_body {
    ($float:ty, $Fixed:ident, $Frac:ty, $Bits:ty, $v:ident) => {{
        // NaN is below +∞ and incomparable with finite values, so the
        // smallest Extended<Q> whose upper image is >= NaN is PosInf.
        if $v.is_nan() {
            $crate::extended::Extended::PosInf
        } else if $v == <$float>::NEG_INFINITY {
            $crate::extended::Extended::NegInf
        } else if $v == <$float>::INFINITY {
            // Explicit +∞ guard — for f16 sources targeting
            // wide-host Q-formats (`<$Bits>::MAX as f16` saturates
            // to +∞), the unified `v > max_v_f64` branch can't
            // distinguish +∞ from saturated `max_v_f64`.
            $crate::extended::Extended::PosInf
        } else {
            let v_f64: f64 = $v as f64;
            let max_q: $Fixed<$Frac> = <$Fixed<$Frac>>::MAX;
            let min_q: $Fixed<$Frac> = <$Fixed<$Frac>>::MIN;
            let max_v_f64: f64 = max_q.to_num::<f64>();
            let min_v_f64: f64 = min_q.to_num::<f64>();
            if v_f64 > max_v_f64 {
                $crate::extended::Extended::PosInf
            } else if v_f64 < min_v_f64 {
                $crate::extended::Extended::Finite(min_q)
            } else {
                let scale: f64 =
                    $crate::float::scale_pow2_f64(<$Frac as ::fixed::types::extra::Unsigned>::U32);
                let scaled: f64 = v_f64 * scale;
                let scaled_ceil: f64 = scaled.ceil();
                let bits: $Bits = scaled_ceil as $Bits;
                // Boundary-saturation overflow detection: when
                // `<$Bits>::MAX` rounds up in f64 (host bits > 53),
                // the strict `v_f64 > max_v_f64` guard above misses
                // the case where `v_f64 == max_v_f64` while
                // `real_v > real_max`. The saturating cast pinned
                // `bits` to MAX; verify via the round-down image
                // of MAX whether the cast actually overflowed.
                // For hosts where MAX is f64-exact (host bits ≤ 32,
                // where the int fits in f64's 53-bit mantissa),
                // `to_f64_rd(MAX) == max_v_f64` and this check is a
                // no-op — `scaled_ceil` ≤ `max_v_f64` in the
                // in-range branch by construction. For wider hosts
                // (i64/u64/i128/u128 storage) it's a live guard.
                if bits == <$Bits>::MAX
                    && <$Bits as $crate::float::BitsToF64Rd>::to_f64_rd(<$Bits>::MAX) < scaled_ceil
                {
                    $crate::extended::Extended::PosInf
                } else {
                    $crate::extended::Extended::Finite(<$Fixed<$Frac>>::from_bits(bits))
                }
            }
        }
    }};
}

#[doc(hidden)]
#[macro_export]
macro_rules! __float_fix_floor_body {
    ($float:ty, $Fixed:ident, $Frac:ty, $Bits:ty, $v:ident) => {{
        if $v.is_nan() {
            $crate::extended::Extended::NegInf
        } else if $v == <$float>::NEG_INFINITY {
            $crate::extended::Extended::NegInf
        } else if $v == <$float>::INFINITY {
            $crate::extended::Extended::PosInf
        } else {
            let v_f64: f64 = $v as f64;
            let max_q: $Fixed<$Frac> = <$Fixed<$Frac>>::MAX;
            let min_q: $Fixed<$Frac> = <$Fixed<$Frac>>::MIN;
            let max_v_f64: f64 = max_q.to_num::<f64>();
            let min_v_f64: f64 = min_q.to_num::<f64>();
            if v_f64 > max_v_f64 {
                $crate::extended::Extended::Finite(max_q)
            } else if v_f64 < min_v_f64 {
                $crate::extended::Extended::NegInf
            } else {
                let scale: f64 =
                    $crate::float::scale_pow2_f64(<$Frac as ::fixed::types::extra::Unsigned>::U32);
                let scaled: f64 = v_f64 * scale;
                let bits: $Bits = scaled.floor() as $Bits;
                $crate::extended::Extended::Finite(<$Fixed<$Frac>>::from_bits(bits))
            }
        }
    }};
}

#[doc(hidden)]
#[macro_export]
macro_rules! __float_fix_inner_body {
    ($float:ty, $Fixed:ident, $Frac:ty, $Bits:ty, $b:ident) => {
        // Finite arm: round-toward-negative-infinity via f64
        // intermediate. The host-bits-to-f64 dispatch uses
        // [`BitsToF64Rd`](crate::float::BitsToF64Rd) so the u128
        // host's top-end saturation (where `u128::MAX as f64` rounds
        // up to `2^128`) is handled correctly — naive `q.to_bits()
        // as i128` would wrap for `bits > i128::MAX` and break
        // L-Galois at the high plateau.
        match $b {
            $crate::extended::Extended::NegInf => $crate::float::N5::new(<$float>::NEG_INFINITY),
            $crate::extended::Extended::PosInf => $crate::float::N5::new(<$float>::INFINITY),
            $crate::extended::Extended::Finite(q) => {
                let approx_f64: f64 = <$Bits as $crate::float::BitsToF64Rd>::to_f64_rd(q.to_bits());
                let scale_neg: f64 = $crate::float::scale_pow2_f64_neg(
                    <$Frac as ::fixed::types::extra::Unsigned>::U32,
                );
                let value_f64: f64 = approx_f64 * scale_neg;
                let value: $float =
                    <$float as $crate::float::RoundDownFromF64>::from_f64_rd(value_f64);
                $crate::float::N5::new(value)
            }
        }
    };
}

/// Emit a full adjoint-triple Conn `Conn<N5<$float>,
/// Extended<$Fixed<$Frac>>>` (impls `ConnL` + `ConnR`) via
/// [`conn_k!`](crate::conn_k).
///
/// Use when `<$Bits>::BITS ≤ <$float>::MANTISSA_DIGITS` so that
/// every Q-format value embeds losslessly into the source float —
/// only then is `inner` order-reflecting.
#[cfg_attr(feature = "macros", macro_export)]
macro_rules! float_fixed {
    ($(#[$meta:meta])* $vis:vis $name:ident, $float:ty, $Fixed:ident, $Frac:ty, $Bits:ty) => {
        $crate::conn_k! {
            $(#[$meta])*
            $vis $name : $crate::float::N5<$float> => $crate::extended::Extended<$Fixed<$Frac>> {
                ceil:  {
                    fn ceil(x: $crate::float::N5<$float>)
                        -> $crate::extended::Extended<$Fixed<$Frac>>
                    {
                        let v = x.into_inner();
                        $crate::__float_fix_ceil_body!($float, $Fixed, $Frac, $Bits, v)
                    }
                    ceil
                },
                inner: {
                    fn inner(b: $crate::extended::Extended<$Fixed<$Frac>>)
                        -> $crate::float::N5<$float>
                    {
                        $crate::__float_fix_inner_body!($float, $Fixed, $Frac, $Bits, b)
                    }
                    inner
                },
                floor: {
                    fn floor(x: $crate::float::N5<$float>)
                        -> $crate::extended::Extended<$Fixed<$Frac>>
                    {
                        let v = x.into_inner();
                        $crate::__float_fix_floor_body!($float, $Fixed, $Frac, $Bits, v)
                    }
                    floor
                },
            }
        }
    };
}

/// Emit an L-only Conn `Conn<N5<$float>,
/// Extended<$Fixed<$Frac>>, L>`.
///
/// Use when `<$Bits>::BITS > <$float>::MANTISSA_DIGITS` so that
/// `inner` aliases distinct Q-format values onto the same float at
/// large magnitudes — the L-Galois adjunction `ceil ⊣ inner` still
/// holds, but `order_reflecting` does not.
#[cfg_attr(feature = "macros", macro_export)]
macro_rules! float_fixed_l {
    ($(#[$meta:meta])* $vis:vis $name:ident, $float:ty, $Fixed:ident, $Frac:ty, $Bits:ty) => {
        $(#[$meta])*
        $vis const $name: $crate::conn::Conn<
            $crate::float::N5<$float>,
            $crate::extended::Extended<$Fixed<$Frac>>,
        > = {
            fn ceil(x: $crate::float::N5<$float>)
                -> $crate::extended::Extended<$Fixed<$Frac>>
            {
                let v = x.into_inner();
                $crate::__float_fix_ceil_body!($float, $Fixed, $Frac, $Bits, v)
            }
            fn inner(b: $crate::extended::Extended<$Fixed<$Frac>>)
                -> $crate::float::N5<$float>
            {
                $crate::__float_fix_inner_body!($float, $Fixed, $Frac, $Bits, b)
            }
            $crate::conn::Conn::new_l(ceil, inner)
        };
    };
}

pub(crate) use float_fixed;
pub(crate) use float_fixed_l;

#[cfg(test)]
mod tests {
    use crate::extended::Extended;
    use fixed::FixedI8;
    use fixed::types::extra::U0;

    #[test]
    fn float_fix_helper_boundary_policy() {
        let v = f32::NAN;
        assert_eq!(
            crate::__float_fix_ceil_body!(f32, FixedI8, U0, i8, v),
            Extended::PosInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f32, FixedI8, U0, i8, v),
            Extended::NegInf
        );

        let v = f32::NEG_INFINITY;
        assert_eq!(
            crate::__float_fix_ceil_body!(f32, FixedI8, U0, i8, v),
            Extended::NegInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f32, FixedI8, U0, i8, v),
            Extended::NegInf
        );

        let v = f32::INFINITY;
        assert_eq!(
            crate::__float_fix_ceil_body!(f32, FixedI8, U0, i8, v),
            Extended::PosInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f32, FixedI8, U0, i8, v),
            Extended::PosInf
        );
    }

    #[cfg(feature = "f16")]
    #[test]
    fn float_fix_helper_f16_wide_boundary_policy() {
        use fixed::FixedI16;

        let v = f16::NAN;
        assert_eq!(
            crate::__float_fix_ceil_body!(f16, FixedI16, U0, i16, v),
            Extended::PosInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f16, FixedI16, U0, i16, v),
            Extended::NegInf
        );

        let v = f16::NEG_INFINITY;
        assert_eq!(
            crate::__float_fix_ceil_body!(f16, FixedI16, U0, i16, v),
            Extended::NegInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f16, FixedI16, U0, i16, v),
            Extended::NegInf
        );

        let v = f16::INFINITY;
        assert_eq!(
            crate::__float_fix_ceil_body!(f16, FixedI16, U0, i16, v),
            Extended::PosInf
        );
        assert_eq!(
            crate::__float_fix_floor_body!(f16, FixedI16, U0, i16, v),
            Extended::PosInf
        );
    }
}

// ── Per-primitive submodules ───────────────────────────────────────

pub mod i008;
pub mod i016;
pub mod i032;
pub mod i064;
pub mod i128;
pub mod u008;
pub mod u016;
pub mod u032;
pub mod u064;
pub mod u128;