miniextendr_api/

coerce.rs

//! Type coercion traits for converting Rust types to R native types.
//!
//! R has a fixed set of native scalar types:
//! - `i32` (INTSXP) - 32-bit signed integer
//! - `f64` (REALSXP) - 64-bit floating point
//! - `RLogical` (LGLSXP) - logical (TRUE/FALSE/NA)
//! - `u8` (RAWSXP) - raw bytes
//! - `Rcomplex` (CPLXSXP) - complex numbers
//!
//! # Traits
//!
//! - [`Coerce<R>`] - infallible coercion (identity, widening)
//! - [`TryCoerce<R>`] - fallible coercion (narrowing, overflow-possible)
//!
//! # Where this fits
//!
//! `Coerce` / `TryCoerce` is the **looser** inbound side — it's the path
//! [`crate::from_r::TryFromSexp`] impls take for multi-source scalars
//! (`i8`/`i16`/`u16`/`u32`/`f32`/`i64`/`u64`/`isize`/`usize`). The strict
//! inbound alternative is the bare `TryFromSexp` impl on the matching R
//! native type (`i32`, `f64`, …), which rejects mismatched
//! [`SEXPTYPE`](crate::SEXPTYPE)s outright. Failure mode of relying on
//! coercion in a function that should be strict: a Rust `i32` argument
//! silently accepts `1.7` (REALSXP) and truncates.
//!
//! The outbound strict-vs-lax pairing lives on [`crate::into_r::IntoR`] (lax,
//! default) vs [`crate::strict`] (`#[miniextendr(strict)]` opt-in).
//!
//! # Examples
//!
//! ```ignore
//! use miniextendr_api::coerce::Coerce;
//!
//! // Scalar coercion
//! let x: i32 = 42i8.coerce();
//!
//! // Element-wise slice coercion
//! let slice: &[i8] = &[1, 2, 3];
//! let vec: Vec<i32> = slice.coerce();
//! ```

use crate::altrep_traits::{NA_INTEGER, NA_LOGICAL, NA_REAL};
use crate::{Rboolean, Rcomplex};

/// Infallible coercion from `Self` to type `R`.
///
/// Implement this trait for types that can always be converted to `R`.
/// Identity and widening conversions should use this trait.
///
/// Pair: [`TryCoerce`] for fallible (narrowing) coercions. Strict alternative
/// on the inbound side: [`crate::from_r::TryFromSexp`].
///
/// Works for both scalars and element-wise on slices:
/// - `i8::coerce() -> i32` (scalar widening)
/// - `&[i8]::coerce() -> Vec<i32>` (element-wise)
///
/// # Example
///
/// ```ignore
/// impl Coerce<i32> for MyType {
///     fn coerce(self) -> i32 { ... }
/// }
/// ```
pub trait Coerce<R> {
    /// Convert `self` into `R`.
    ///
    /// This conversion must not fail.
    fn coerce(self) -> R;
}

/// Fallible coercion from `Self` to type `R`.
///
/// Implement this trait for narrowing conversions that may overflow or lose precision.
///
/// Pair: [`Coerce`] for infallible (widening / identity) coercions. Strict
/// alternative on the inbound side: [`crate::from_r::TryFromSexp`].
pub trait TryCoerce<R> {
    /// Error returned when coercion fails.
    type Error;
    /// Attempt to convert `self` into `R`.
    fn try_coerce(self) -> Result<R, Self::Error>;
}

/// Error type for coercion failures.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CoerceError {
    /// The value cannot fit in the destination range.
    Overflow,
    /// The destination type cannot represent this value exactly.
    PrecisionLoss,
    /// The input was NaN and destination disallows it.
    NaN,
    /// Zero is not allowed by the conversion rule.
    Zero,
}

impl std::fmt::Display for CoerceError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CoerceError::Overflow => write!(f, "value out of range"),
            CoerceError::PrecisionLoss => write!(f, "precision loss"),
            CoerceError::NaN => write!(f, "NaN cannot be converted"),
            CoerceError::Zero => write!(f, "zero not allowed"),
        }
    }
}

impl std::error::Error for CoerceError {}

// region: Blanket: Coerce implies TryCoerce

impl<T, R> TryCoerce<R> for T
where
    T: Coerce<R>,
{
    type Error = std::convert::Infallible;

    #[inline(always)]
    fn try_coerce(self) -> Result<R, Self::Error> {
        Ok(self.coerce())
    }
}
// endregion

// region: Identity coercions
//
// Note: Can't use blanket `impl<T> Coerce<T> for T` because it would conflict
// with container coercion impls like `impl<T: Coerce<R>> Coerce<Vec<R>> for Vec<T>`.
// Both would apply to `Vec<T>: Coerce<Vec<T>>`, causing overlap.

macro_rules! impl_identity {
    ($t:ty) => {
        impl Coerce<$t> for $t {
            #[inline(always)]
            fn coerce(self) -> $t {
                self
            }
        }
    };
}

impl_identity!(i32);
impl_identity!(f64);
impl_identity!(Rboolean);
impl_identity!(u8);
impl_identity!(Rcomplex);
// endregion

// region: Scalar coercion macros (shared by the widening / narrowing blocks below)

/// Implement infallible widening `Coerce<$to>` for each `$from => $to` pair via `Into`.
///
/// For widenings that have no `From` impl (platform-dependent `isize`/`usize`,
/// lossy int→float), write the `impl Coerce` by hand with an `as` cast instead.
macro_rules! impl_widen {
    ($($from:ty => $to:ty),+ $(,)?) => {
        $(
            impl Coerce<$to> for $from {
                #[inline(always)]
                fn coerce(self) -> $to {
                    self.into()
                }
            }
        )+
    };
}

/// Implement fallible narrowing `TryCoerce<$target>` for each `$from` via
/// `try_into` (overflow → `CoerceError::Overflow`).
macro_rules! impl_try_narrow {
    ($target:ty; $($from:ty),+ $(,)?) => {
        $(
            impl TryCoerce<$target> for $from {
                type Error = CoerceError;
                #[inline]
                fn try_coerce(self) -> Result<$target, CoerceError> {
                    self.try_into().map_err(|_| CoerceError::Overflow)
                }
            }
        )+
    };
}
// endregion

// region: Widening conversions (blanket impls using marker traits)

/// Blanket impl: Any type that widens to i32 can be coerced to i32.
///
/// This replaces individual macro invocations with a single blanket impl.
/// Covers: i8, i16, u8, u16 (all types where T: `Into<i32>`).
impl<T: crate::markers::WidensToI32> Coerce<i32> for T {
    #[inline(always)]
    fn coerce(self) -> i32 {
        self.into()
    }
}

/// Blanket impl: Any type that widens to f64 can be coerced to f64.
///
/// This replaces individual macro invocations with a single blanket impl.
/// Covers: f32, i8, i16, i32, u8, u16, u32 (all types where T: `Into<f64>`).
impl<T: crate::markers::WidensToF64> Coerce<f64> for T {
    #[inline(always)]
    fn coerce(self) -> f64 {
        self.into()
    }
}
// endregion

// region: Widening from u8 to larger integer/float types

impl_widen!(u8 => i64, u8 => isize, u8 => u64, u8 => usize, u8 => f32);

impl Coerce<f32> for i32 {
    #[inline(always)]
    fn coerce(self) -> f32 {
        self as f32
    }
}
// endregion

// region: bool coercions

impl Coerce<Rboolean> for bool {
    #[inline(always)]
    fn coerce(self) -> Rboolean {
        if self {
            Rboolean::TRUE
        } else {
            Rboolean::FALSE
        }
    }
}

impl Coerce<i32> for bool {
    #[inline(always)]
    fn coerce(self) -> i32 {
        if self { 1 } else { 0 }
    }
}

impl Coerce<f64> for bool {
    #[inline(always)]
    fn coerce(self) -> f64 {
        if self { 1.0 } else { 0.0 }
    }
}

impl Coerce<i32> for Rboolean {
    #[inline(always)]
    fn coerce(self) -> i32 {
        self as i32
    }
}
// endregion

// region: Option<T> to R-native with None → NA

/// `Option<f64>` → `f64` with `None` → `NA_real_`.
impl Coerce<f64> for Option<f64> {
    #[inline(always)]
    fn coerce(self) -> f64 {
        self.unwrap_or(NA_REAL)
    }
}

/// `Option<i32>` → `i32` with `None` → `NA_integer_`.
impl Coerce<i32> for Option<i32> {
    #[inline(always)]
    fn coerce(self) -> i32 {
        self.unwrap_or(NA_INTEGER)
    }
}

/// `Option<bool>` → `i32` with `None` → `NA_LOGICAL`.
impl Coerce<i32> for Option<bool> {
    #[inline(always)]
    fn coerce(self) -> i32 {
        match self {
            Some(true) => 1,
            Some(false) => 0,
            None => NA_LOGICAL,
        }
    }
}

/// `Option<Rboolean>` → `i32` with `None` → `NA_LOGICAL`.
impl Coerce<i32> for Option<Rboolean> {
    #[inline(always)]
    fn coerce(self) -> i32 {
        match self {
            Some(v) => v as i32,
            None => NA_LOGICAL,
        }
    }
}
// endregion

// region: i32 to larger/unsigned types (for argument coercion from R integers)

/// i32 -> i64: widening, always safe
impl Coerce<i64> for i32 {
    #[inline(always)]
    fn coerce(self) -> i64 {
        self.into()
    }
}

/// i32 -> isize: always safe (isize is at least 32 bits)
impl Coerce<isize> for i32 {
    #[inline(always)]
    fn coerce(self) -> isize {
        self as isize
    }
}

/// i32 -> u32: can fail if negative
impl TryCoerce<u32> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u32, CoerceError> {
        self.try_into().map_err(|_| CoerceError::Overflow)
    }
}

/// i32 -> u64: can fail if negative
impl TryCoerce<u64> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u64, CoerceError> {
        self.try_into().map_err(|_| CoerceError::Overflow)
    }
}

/// i32 -> usize: can fail if negative
impl TryCoerce<usize> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<usize, CoerceError> {
        self.try_into().map_err(|_| CoerceError::Overflow)
    }
}
// endregion

// region: NonZero conversions (fallible - zero check)

use core::num::{
    NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroIsize, NonZeroU8, NonZeroU16, NonZeroU32,
    NonZeroU64, NonZeroUsize,
};

macro_rules! impl_nonzero_from_self {
    ($base:ty, $nz:ty) => {
        impl TryCoerce<$nz> for $base {
            type Error = CoerceError;

            #[inline]
            fn try_coerce(self) -> Result<$nz, CoerceError> {
                <$nz>::new(self).ok_or(CoerceError::Zero)
            }
        }
    };
}

// Direct NonZero conversions (same base type)
impl_nonzero_from_self!(i8, NonZeroI8);
impl_nonzero_from_self!(i16, NonZeroI16);
impl_nonzero_from_self!(i32, NonZeroI32);
impl_nonzero_from_self!(i64, NonZeroI64);
impl_nonzero_from_self!(isize, NonZeroIsize);
impl_nonzero_from_self!(u8, NonZeroU8);
impl_nonzero_from_self!(u16, NonZeroU16);
impl_nonzero_from_self!(u32, NonZeroU32);
impl_nonzero_from_self!(u64, NonZeroU64);
impl_nonzero_from_self!(usize, NonZeroUsize);

/// i32 -> NonZeroI64: widen then check zero
impl TryCoerce<NonZeroI64> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroI64, CoerceError> {
        NonZeroI64::new(self.into()).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroIsize: widen then check zero
impl TryCoerce<NonZeroIsize> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroIsize, CoerceError> {
        NonZeroIsize::new(self as isize).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroU32: check non-negative and non-zero
impl TryCoerce<NonZeroU32> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroU32, CoerceError> {
        let u: u32 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroU32::new(u).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroU64: check non-negative and non-zero
impl TryCoerce<NonZeroU64> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroU64, CoerceError> {
        let u: u64 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroU64::new(u).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroUsize: check non-negative and non-zero
impl TryCoerce<NonZeroUsize> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroUsize, CoerceError> {
        let u: usize = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroUsize::new(u).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroI8: narrow then check zero
impl TryCoerce<NonZeroI8> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroI8, CoerceError> {
        let n: i8 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroI8::new(n).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroI16: narrow then check zero
impl TryCoerce<NonZeroI16> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroI16, CoerceError> {
        let n: i16 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroI16::new(n).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroU8: check non-negative, narrow, then check zero
impl TryCoerce<NonZeroU8> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroU8, CoerceError> {
        let u: u8 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroU8::new(u).ok_or(CoerceError::Zero)
    }
}

/// i32 -> NonZeroU16: check non-negative, narrow, then check zero
impl TryCoerce<NonZeroU16> for i32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<NonZeroU16, CoerceError> {
        let u: u16 = self.try_into().map_err(|_| CoerceError::Overflow)?;
        NonZeroU16::new(u).ok_or(CoerceError::Zero)
    }
}
// endregion

// region: i32/Rboolean to bool (fallible - NA handling)

/// Error type for logical coercion failures.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogicalCoerceError {
    /// R's NA_LOGICAL cannot be represented as Rust bool
    NAValue,
    /// Value is not 0 or 1
    InvalidValue(i32),
}

impl std::fmt::Display for LogicalCoerceError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            LogicalCoerceError::NAValue => write!(f, "NA cannot be converted to bool"),
            LogicalCoerceError::InvalidValue(v) => write!(f, "invalid logical value: {}", v),
        }
    }
}

impl std::error::Error for LogicalCoerceError {}

impl TryCoerce<bool> for i32 {
    type Error = LogicalCoerceError;

    #[inline]
    fn try_coerce(self) -> Result<bool, LogicalCoerceError> {
        match self {
            0 => Ok(false),
            1 => Ok(true),
            // NA_LOGICAL is i32::MIN in R
            i32::MIN => Err(LogicalCoerceError::NAValue),
            other => Err(LogicalCoerceError::InvalidValue(other)),
        }
    }
}

impl TryCoerce<bool> for Rboolean {
    type Error = LogicalCoerceError;

    #[inline]
    fn try_coerce(self) -> Result<bool, LogicalCoerceError> {
        (self as i32).try_coerce()
    }
}

impl TryCoerce<bool> for crate::RLogical {
    type Error = LogicalCoerceError;

    #[inline]
    fn try_coerce(self) -> Result<bool, LogicalCoerceError> {
        self.to_i32().try_coerce()
    }
}
// endregion

// region: Narrowing to i32 (fallible)

impl_try_narrow!(i32; u32, u64, usize, i64, isize);
// endregion

// region: Narrowing to u8 (fallible)

impl_try_narrow!(u8; i8, i16, i32, i64, u16, u32, u64, usize, isize);
// endregion

// region: Widening to u16/i16/u32 (infallible)

impl_widen!(u8 => u16, i8 => i16, u8 => i16, u8 => u32, u16 => u32);
// endregion

// region: Narrowing to u16 (fallible)

impl_try_narrow!(u16; i8, i16, i32, i64, u32, u64, usize, isize);
// endregion

// region: Narrowing to i16 (fallible)

impl_try_narrow!(i16; i32, i64, u16, u32, u64, usize, isize);
// endregion

// region: Narrowing to i8 (fallible)

impl_try_narrow!(i8; i16, i32, i64, u8, u16, u32, u64, usize, isize);
// endregion

// region: Float to smaller integers (fallible)

impl TryCoerce<u16> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u16, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < 0.0 || self > u16::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as u16)
    }
}

impl TryCoerce<i16> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<i16, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < i16::MIN as f64 || self > i16::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as i16)
    }
}

impl TryCoerce<i8> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<i8, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < i8::MIN as f64 || self > i8::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as i8)
    }
}
// endregion

// region: Float to i32 (fallible)

impl TryCoerce<i32> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<i32, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < i32::MIN as f64 || self > i32::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as i32)
    }
}

impl TryCoerce<i32> for f32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<i32, CoerceError> {
        f64::from(self).try_coerce()
    }
}

// f64 → f32 narrowing (always succeeds, may lose precision or become inf)
impl Coerce<f32> for f64 {
    #[inline(always)]
    fn coerce(self) -> f32 {
        self as f32
    }
}
// endregion

// region: Float to u8 (fallible) - for RAWSXP

impl TryCoerce<u8> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u8, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < 0.0 || self > u8::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as u8)
    }
}

impl TryCoerce<u8> for f32 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u8, CoerceError> {
        f64::from(self).try_coerce()
    }
}
// endregion

// region: Float to u32 (fallible)

impl TryCoerce<u32> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u32, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < 0.0 || self > u32::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as u32)
    }
}
// endregion

// region: Float to i64/u64 (fallible)
//
// These conversions validate that the f64 can be exactly represented as an integer.
//
// **Checks performed:**
// - NaN → `Err(CoerceError::NaN)`
// - Infinity → `Err(CoerceError::Overflow)`
// - Out of range → `Err(CoerceError::Overflow)`
// - Has fractional part → `Err(CoerceError::PrecisionLoss)`
//
// **Note on precision:**
// f64 can exactly represent all integers in [-2^53, 2^53]. For values in this
// range that pass the fractional check, conversion is exact. For larger f64
// values (which must have been created through approximation), the conversion
// returns whatever integer the f64 represents, which may not be what was
// originally intended.

/// Convert `f64` to `i64`, validating exact representation.
impl TryCoerce<i64> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<i64, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        // i64::MIN/MAX can't be exactly represented in f64, so use safe bounds
        if self < i64::MIN as f64 || self >= i64::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as i64)
    }
}

impl TryCoerce<u64> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<u64, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        if self < 0.0 || self >= u64::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as u64)
    }
}

impl TryCoerce<isize> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<isize, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        // Upper check uses >= because isize::MAX as f64 rounds up on 64-bit
        if self < isize::MIN as f64 || self >= isize::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as isize)
    }
}

impl TryCoerce<usize> for f64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<usize, CoerceError> {
        if self.is_nan() {
            return Err(CoerceError::NaN);
        }
        if self.is_infinite() {
            return Err(CoerceError::Overflow);
        }
        // Upper check uses >= because usize::MAX as f64 rounds up on 64-bit
        if self < 0.0 || self >= usize::MAX as f64 {
            return Err(CoerceError::Overflow);
        }
        if self.fract() != 0.0 {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as usize)
    }
}
// endregion

// region: Large int to f64 (fallible - precision)
//
// These conversions only succeed if the integer can be exactly represented
// in f64. This is stricter than Rust's `as f64` which silently rounds.
//
// **Safe integer range:**
// - f64 has 53 bits of mantissa precision
// - Integers in [-2^53, 2^53] (±9,007,199,254,740,992) are exactly representable
// - Outside this range: `Err(CoerceError::PrecisionLoss)`
//
// **Use cases:**
// - Validating R function inputs won't lose precision
// - Checked conversions in data pipelines
// - Ensuring round-trip fidelity (i64 → R → i64)

/// Convert `i64` to `f64`, failing if precision would be lost.
///
/// Only succeeds for values in [-2^53, 2^53].
impl TryCoerce<f64> for i64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<f64, CoerceError> {
        const MAX_SAFE: i64 = 1 << 53;
        const MIN_SAFE: i64 = -(1 << 53);
        if !(MIN_SAFE..=MAX_SAFE).contains(&self) {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as f64)
    }
}

/// Convert `u64` to `f64`, failing if precision would be lost.
///
/// Only succeeds for values ≤ 2^53.
impl TryCoerce<f64> for u64 {
    type Error = CoerceError;

    #[inline]
    fn try_coerce(self) -> Result<f64, CoerceError> {
        const MAX_SAFE: u64 = 1 << 53;
        if self > MAX_SAFE {
            return Err(CoerceError::PrecisionLoss);
        }
        Ok(self as f64)
    }
}

impl TryCoerce<f64> for isize {
    type Error = CoerceError;
    #[inline]
    fn try_coerce(self) -> Result<f64, CoerceError> {
        (self as i64).try_coerce()
    }
}

impl TryCoerce<f64> for usize {
    type Error = CoerceError;
    #[inline]
    fn try_coerce(self) -> Result<f64, CoerceError> {
        (self as u64).try_coerce()
    }
}
// endregion

// region: Coerced wrapper type

use std::marker::PhantomData;

/// Wrapper for values coerced from an R native type during conversion.
///
/// This enables using non-native Rust types in collections read from R:
///
/// ```ignore
/// // Read a Vec of i64 from R integers (i32)
/// let vec: Vec<Coerced<i64, i32>> = TryFromSexp::try_from_sexp(sexp)?;
///
/// // Extract the values
/// let i64_vec: Vec<i64> = vec.into_iter().map(Coerced::into_inner).collect();
/// ```
///
/// The type parameters are:
/// - `T`: The target Rust type you want
/// - `R`: The R-native type to read and coerce from
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Coerced<T, R> {
    value: T,
    _marker: PhantomData<R>,
}

impl<T, R> Coerced<T, R> {
    /// Create a new Coerced wrapper.
    #[inline]
    pub const fn new(value: T) -> Self {
        Self {
            value,
            _marker: PhantomData,
        }
    }

    /// Extract the inner value.
    #[inline]
    pub fn into_inner(self) -> T {
        self.value
    }

    /// Get a reference to the inner value.
    #[inline]
    pub const fn as_inner(&self) -> &T {
        &self.value
    }

    /// Get a mutable reference to the inner value.
    #[inline]
    pub fn as_inner_mut(&mut self) -> &mut T {
        &mut self.value
    }
}

impl<T, R> std::ops::Deref for Coerced<T, R> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

impl<T, R> std::ops::DerefMut for Coerced<T, R> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.value
    }
}
// endregion

// region: Slice coercions (element-wise)

/// Coerce a slice element-wise to a Vec.
impl<T: Copy + Coerce<R>, R> Coerce<Vec<R>> for &[T] {
    #[inline]
    fn coerce(self) -> Vec<R> {
        self.iter().copied().map(Coerce::coerce).collect()
    }
}

/// Coerce a Vec element-wise to a new Vec.
impl<T: Coerce<R>, R> Coerce<Vec<R>> for Vec<T> {
    #[inline]
    fn coerce(self) -> Vec<R> {
        self.into_iter().map(Coerce::coerce).collect()
    }
}

/// Infallible element-wise coercion for `Box<[T]>` → `Box<[R]>`.
impl<T: Coerce<R>, R> Coerce<Box<[R]>> for Box<[T]> {
    #[inline]
    fn coerce(self) -> Box<[R]> {
        Vec::from(self).into_iter().map(Coerce::coerce).collect()
    }
}

/// Infallible element-wise coercion for VecDeque to VecDeque.
impl<T: Coerce<R>, R> Coerce<std::collections::VecDeque<R>> for std::collections::VecDeque<T> {
    fn coerce(self) -> std::collections::VecDeque<R> {
        self.into_iter().map(Coerce::coerce).collect()
    }
}

// Note: TryCoerce<Vec<R>> is automatically provided by the blanket impl
// `impl<T: Coerce<R>> TryCoerce<R> for T`. For types that only implement
// TryCoerce (not Coerce), use manual iteration:
// slice.iter().map(|x| x.try_coerce()).collect::<Result<Vec<_>, _>>()
// endregion

// region: TinyVec coercions (element-wise)

#[cfg(feature = "tinyvec")]
/// Element-wise coercion for TinyVec.
///
/// Enables conversions like `TinyVec<[i8; 10]>` → `TinyVec<[i32; 10]>` via widening.
impl<T, R, const N: usize> Coerce<tinyvec::TinyVec<[R; N]>> for tinyvec::TinyVec<[T; N]>
where
    T: Coerce<R>,
    [T; N]: tinyvec::Array<Item = T>,
    [R; N]: tinyvec::Array<Item = R>,
{
    fn coerce(self) -> tinyvec::TinyVec<[R; N]> {
        self.into_iter().map(Coerce::coerce).collect()
    }
}

#[cfg(feature = "tinyvec")]
/// Element-wise coercion for ArrayVec.
///
/// Enables conversions like `ArrayVec<[i8; 10]>` → `ArrayVec<[i32; 10]>` via widening.
impl<T, R, const N: usize> Coerce<tinyvec::ArrayVec<[R; N]>> for tinyvec::ArrayVec<[T; N]>
where
    T: Coerce<R>,
    [T; N]: tinyvec::Array<Item = T>,
    [R; N]: tinyvec::Array<Item = R>,
{
    fn coerce(self) -> tinyvec::ArrayVec<[R; N]> {
        self.into_iter().map(Coerce::coerce).collect()
    }
}
// endregion

// region: Tuple coercions (element-wise)

/// Macro to implement element-wise Coerce for tuples.
macro_rules! impl_tuple_coerce {
    (($($T:ident),+), ($($R:ident),+), ($($idx:tt),+)) => {
        impl<$($T,)+ $($R,)+> Coerce<($($R,)+)> for ($($T,)+)
        where
            $($T: Coerce<$R>,)+
        {
            #[inline]
            fn coerce(self) -> ($($R,)+) {
                ($(Coerce::<$R>::coerce(self.$idx),)+)
            }
        }
    };
}

// Implement for tuples of sizes 2-8
impl_tuple_coerce!((A, B), (RA, RB), (0, 1));
impl_tuple_coerce!((A, B, C), (RA, RB, RC), (0, 1, 2));
impl_tuple_coerce!((A, B, C, D), (RA, RB, RC, RD), (0, 1, 2, 3));
impl_tuple_coerce!((A, B, C, D, E), (RA, RB, RC, RD, RE), (0, 1, 2, 3, 4));
impl_tuple_coerce!(
    (A, B, C, D, E, F),
    (RA, RB, RC, RD, RE, RF),
    (0, 1, 2, 3, 4, 5)
);
impl_tuple_coerce!(
    (A, B, C, D, E, F, G),
    (RA, RB, RC, RD, RE, RF, RG),
    (0, 1, 2, 3, 4, 5, 6)
);
impl_tuple_coerce!(
    (A, B, C, D, E, F, G, H),
    (RA, RB, RC, RD, RE, RF, RG, RH),
    (0, 1, 2, 3, 4, 5, 6, 7)
);
// endregion

// region: Tests

#[cfg(test)]
mod tests;
// endregion