miniextendr_api/

into_r_as.rs

//! Storage-directed conversion to R.
//!
//! This module provides [`IntoRAs`], a trait for converting Rust values to R SEXPs
//! with explicit target storage type selection.
//!
//! # Value-Based Semantics
//!
//! Conversions are **runtime-checked**: if the actual value fits the target type,
//! it converts; if not, it errors. There is no "lossy" escape hatch - if you want
//! lossy conversion, cast the values yourself first.
//!
//! # Where this fits among the three outbound paths
//!
//! - [`crate::into_r::IntoR`] — **lax** default: picks an R storage type for
//!   you (e.g. `i64` → `INTSXP` if it fits, `REALSXP` otherwise). Silent.
//! - [`crate::strict`] — **strict** opt-in via `#[miniextendr(strict)]`:
//!   panics (→ R error) if the value can't fit `INTSXP`.
//! - `IntoRAs` (this module) — **storage-directed**: the *caller* picks the
//!   target R type, the conversion errors with [`StorageCoerceError`] if any
//!   value doesn't fit.
//!
//! Failure mode of reaching for the default `IntoR` when you actually wanted
//! storage control: an R-side `is.integer()` check fails because R received
//! a `REALSXP` your `tibble` column wasn't expecting.
//!
//! # Example
//!
//! ```ignore
//! use miniextendr_api::IntoRAs;
//!
//! // These succeed (values fit)
//! let x = vec![1_i64, 2, 3];
//! let sexp = x.into_r_as::<i32>()?;           // OK: all values in i32 range
//!
//! let y = vec![1.0_f64, 2.0, 3.0];
//! let sexp = y.into_r_as::<i32>()?;           // OK: all values are integral
//!
//! // These fail (values don't fit)
//! let z = vec![1_i64 << 40];
//! let sexp = z.into_r_as::<i32>()?;           // Error: out of range
//!
//! let w = vec![1.5_f64];
//! let sexp = w.into_r_as::<i32>()?;           // Error: not integral
//!
//! // User wants lossy? Cast first.
//! let lossy: Vec<i32> = vec![1.5_f64, 2.7].iter().map(|&x| x as i32).collect();
//! let sexp = lossy.into_r();                  // [1, 2] - user's responsibility
//! ```

use crate::coerce::{CoerceError, TryCoerce};
use crate::from_r::BATCHED_ERROR_CAP;
use crate::into_r::IntoR;
use crate::{RLogical, SEXP};
use std::fmt;

// region: Error type

/// Error type for storage-directed conversion failures.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StorageCoerceError {
    /// Conversion between these types is not supported.
    Unsupported {
        /// Source Rust type name.
        from: &'static str,
        /// Target storage type name.
        to: &'static str,
    },
    /// Value is out of range for the target type.
    OutOfRange {
        /// Source Rust type name.
        from: &'static str,
        /// Target storage type name.
        to: &'static str,
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Value is non-finite (NaN or Inf) but target requires finite.
    NonFinite {
        /// Target storage type name.
        to: &'static str,
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Conversion would lose precision.
    PrecisionLoss {
        /// Target storage type name.
        to: &'static str,
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Float value is not integral but target is integer type.
    NotIntegral {
        /// Target storage type name.
        to: &'static str,
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Missing value (NA) cannot be represented in target type.
    MissingValue {
        /// Target storage type name.
        to: &'static str,
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Invalid UTF-8 in string conversion.
    InvalidUtf8 {
        /// Failing element index for vector conversions.
        index: Option<usize>,
    },
    /// Aggregated per-element failures from a vector conversion (#1097).
    /// `listed` holds at most the first `BATCHED_ERROR_CAP` element errors
    /// (each with `index` set); `total` counts all failures.
    Batched {
        /// The vector/slice type that failed to convert, e.g. `"Vec<i64>"`.
        container: &'static str,
        /// The first `BATCHED_ERROR_CAP` per-element failures.
        listed: Vec<StorageCoerceError>,
        /// Total number of failing elements (`>= listed.len()`).
        total: usize,
    },
}

impl fmt::Display for StorageCoerceError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StorageCoerceError::Unsupported { from, to } => {
                write!(f, "cannot convert {} to {}", from, to)
            }
            StorageCoerceError::OutOfRange { from, to, index } => {
                if let Some(i) = index {
                    write!(f, "value at index {} out of range for {} → {}", i, from, to)
                } else {
                    write!(f, "value out of range for {} → {}", from, to)
                }
            }
            StorageCoerceError::NonFinite { to, index } => {
                if let Some(i) = index {
                    write!(
                        f,
                        "non-finite value at index {} cannot convert to {}",
                        i, to
                    )
                } else {
                    write!(f, "non-finite value cannot convert to {}", to)
                }
            }
            StorageCoerceError::PrecisionLoss { to, index } => {
                if let Some(i) = index {
                    write!(
                        f,
                        "value at index {} would lose precision converting to {}",
                        i, to
                    )
                } else {
                    write!(f, "value would lose precision converting to {}", to)
                }
            }
            StorageCoerceError::NotIntegral { to, index } => {
                if let Some(i) = index {
                    write!(
                        f,
                        "non-integral value at index {} cannot convert to {}",
                        i, to
                    )
                } else {
                    write!(f, "non-integral value cannot convert to {}", to)
                }
            }
            StorageCoerceError::MissingValue { to, index } => {
                if let Some(i) = index {
                    write!(f, "missing value at index {} cannot convert to {}", i, to)
                } else {
                    write!(f, "missing value cannot convert to {}", to)
                }
            }
            StorageCoerceError::InvalidUtf8 { index } => {
                if let Some(i) = index {
                    write!(f, "invalid UTF-8 at index {}", i)
                } else {
                    write!(f, "invalid UTF-8")
                }
            }
            StorageCoerceError::Batched {
                container,
                listed,
                total,
            } => {
                write!(f, "{} conversion failed: ", container)?;
                for (i, e) in listed.iter().enumerate() {
                    if i > 0 {
                        write!(f, "; ")?;
                    }
                    write!(f, "{}", e)?;
                }
                if *total > listed.len() {
                    write!(f, "; and {} more", total - listed.len())?;
                }
                Ok(())
            }
        }
    }
}

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

impl StorageCoerceError {
    /// Add index information to the error.
    #[inline]
    pub fn at_index(self, idx: usize) -> Self {
        match self {
            StorageCoerceError::OutOfRange { from, to, .. } => StorageCoerceError::OutOfRange {
                from,
                to,
                index: Some(idx),
            },
            StorageCoerceError::NonFinite { to, .. } => StorageCoerceError::NonFinite {
                to,
                index: Some(idx),
            },
            StorageCoerceError::PrecisionLoss { to, .. } => StorageCoerceError::PrecisionLoss {
                to,
                index: Some(idx),
            },
            StorageCoerceError::NotIntegral { to, .. } => StorageCoerceError::NotIntegral {
                to,
                index: Some(idx),
            },
            StorageCoerceError::MissingValue { to, .. } => StorageCoerceError::MissingValue {
                to,
                index: Some(idx),
            },
            StorageCoerceError::InvalidUtf8 { .. } => {
                StorageCoerceError::InvalidUtf8 { index: Some(idx) }
            }
            // Batched errors already carry per-element indices on their
            // `listed` entries — indexing the aggregate itself is a no-op.
            batched @ StorageCoerceError::Batched { .. } => batched,
            other => other,
        }
    }
}
// endregion

// region: Trait definition

/// Storage-directed conversion to R SEXP.
///
/// This trait allows converting Rust values to R with an explicit target storage
/// type. The conversion is value-based: it succeeds if all values fit the target
/// type, and fails otherwise.
///
/// # Target Types
///
/// - `i32` → R integer (INTSXP)
/// - `f64` → R numeric (REALSXP)
/// - `RLogical` → R logical (LGLSXP)
/// - `u8` → R raw (RAWSXP)
/// - `String` → R character (STRSXP)
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::IntoRAs;
///
/// // Convert i64 to R integer (if values fit)
/// let x: Vec<i64> = vec![1, 2, 3];
/// let sexp = x.into_r_as::<i32>()?;
///
/// // Convert f64 to R integer (if values are integral)
/// let y: Vec<f64> = vec![1.0, 2.0, 3.0];
/// let sexp = y.into_r_as::<i32>()?;
/// ```
pub trait IntoRAs<Target> {
    /// Convert to R SEXP with the specified target storage type.
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError>;
}
// endregion

// region: Helper: try_coerce_scalar with error mapping

/// Try to coerce a scalar value, mapping CoerceError to StorageCoerceError.
#[inline]
fn try_coerce_scalar<T, R>(
    value: T,
    from: &'static str,
    to: &'static str,
) -> Result<R, StorageCoerceError>
where
    T: TryCoerce<R>,
    T::Error: Into<CoerceErrorKind>,
{
    value
        .try_coerce()
        .map_err(|e| map_coerce_error(e.into(), from, to))
}

/// Internal enum to unify different coerce error types.
#[derive(Debug)]
enum CoerceErrorKind {
    Overflow,
    PrecisionLoss,
    NaN,
    Infallible,
}

impl From<CoerceError> for CoerceErrorKind {
    fn from(e: CoerceError) -> Self {
        match e {
            CoerceError::Overflow => CoerceErrorKind::Overflow,
            CoerceError::PrecisionLoss => CoerceErrorKind::PrecisionLoss,
            CoerceError::NaN => CoerceErrorKind::NaN,
            CoerceError::Zero => CoerceErrorKind::Overflow, // Treat zero error as overflow
        }
    }
}

impl From<std::convert::Infallible> for CoerceErrorKind {
    fn from(_: std::convert::Infallible) -> Self {
        CoerceErrorKind::Infallible
    }
}

fn map_coerce_error(
    kind: CoerceErrorKind,
    from: &'static str,
    to: &'static str,
) -> StorageCoerceError {
    match kind {
        CoerceErrorKind::Overflow => StorageCoerceError::OutOfRange {
            from,
            to,
            index: None,
        },
        CoerceErrorKind::PrecisionLoss => StorageCoerceError::PrecisionLoss { to, index: None },
        CoerceErrorKind::NaN => StorageCoerceError::NonFinite { to, index: None },
        CoerceErrorKind::Infallible => unreachable!(),
    }
}
// endregion

// region: Scalar implementations: -> i32 (R integer)

macro_rules! impl_into_r_as_scalar {
    ($target:ty, $target_name:literal; $from:ty, $from_name:literal) => {
        impl IntoRAs<$target> for $from {
            #[inline]
            fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
                let v: $target = try_coerce_scalar(self, $from_name, $target_name)?;
                Ok(v.into_sexp())
            }
        }
    };
}

// Identity
impl IntoRAs<i32> for i32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

// Widening (infallible)
impl_into_r_as_scalar!(i32, "i32"; i8, "i8");
impl_into_r_as_scalar!(i32, "i32"; i16, "i16");
impl_into_r_as_scalar!(i32, "i32"; u8, "u8");
impl_into_r_as_scalar!(i32, "i32"; u16, "u16");

// Narrowing (fallible)
impl_into_r_as_scalar!(i32, "i32"; i64, "i64");
impl_into_r_as_scalar!(i32, "i32"; isize, "isize");
impl_into_r_as_scalar!(i32, "i32"; u32, "u32");
impl_into_r_as_scalar!(i32, "i32"; u64, "u64");
impl_into_r_as_scalar!(i32, "i32"; usize, "usize");

// Float to int (fallible - must be integral and in range)
impl_into_r_as_scalar!(i32, "i32"; f32, "f32");
impl_into_r_as_scalar!(i32, "i32"; f64, "f64");

// Bool to int
impl IntoRAs<i32> for bool {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as i32).into_sexp())
    }
}
// endregion

// region: Scalar implementations: -> f64 (R numeric)

// Identity
impl IntoRAs<f64> for f64 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        if !self.is_finite() {
            return Err(StorageCoerceError::NonFinite {
                to: "f64",
                index: None,
            });
        }
        Ok(self.into_sexp())
    }
}

// Widening from f32 (check finite)
impl IntoRAs<f64> for f32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        if !self.is_finite() {
            return Err(StorageCoerceError::NonFinite {
                to: "f64",
                index: None,
            });
        }
        Ok((self as f64).into_sexp())
    }
}

// Widening from integers (infallible for small types)
impl IntoRAs<f64> for i8 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as f64).into_sexp())
    }
}

impl IntoRAs<f64> for i16 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as f64).into_sexp())
    }
}

impl IntoRAs<f64> for i32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        // i32::MIN is R's NA_integer_ sentinel. A blind `self as f64` would
        // turn it into the finite value -2147483648.0, silently destroying the
        // missing-value semantics. Detect it and surface MissingValue instead.
        if self == crate::altrep_traits::NA_INTEGER {
            return Err(StorageCoerceError::MissingValue {
                to: "f64",
                index: None,
            });
        }
        Ok((self as f64).into_sexp())
    }
}

impl IntoRAs<f64> for u8 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as f64).into_sexp())
    }
}

impl IntoRAs<f64> for u16 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as f64).into_sexp())
    }
}

impl IntoRAs<f64> for u32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((self as f64).into_sexp())
    }
}

// Large integers: check precision (> 2^53 loses precision)
impl_into_r_as_scalar!(f64, "f64"; i64, "i64");
impl_into_r_as_scalar!(f64, "f64"; u64, "u64");
impl_into_r_as_scalar!(f64, "f64"; isize, "isize");
impl_into_r_as_scalar!(f64, "f64"; usize, "usize");

// Bool to f64
impl IntoRAs<f64> for bool {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((if self { 1.0 } else { 0.0 }).into_sexp())
    }
}
// endregion

// region: Scalar implementations: -> u8 (R raw)

// Identity
impl IntoRAs<u8> for u8 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

// Narrowing (fallible)
impl_into_r_as_scalar!(u8, "u8"; i8, "i8");
impl_into_r_as_scalar!(u8, "u8"; i16, "i16");
impl_into_r_as_scalar!(u8, "u8"; i32, "i32");
impl_into_r_as_scalar!(u8, "u8"; i64, "i64");
impl_into_r_as_scalar!(u8, "u8"; isize, "isize");
impl_into_r_as_scalar!(u8, "u8"; u16, "u16");
impl_into_r_as_scalar!(u8, "u8"; u32, "u32");
impl_into_r_as_scalar!(u8, "u8"; u64, "u64");
impl_into_r_as_scalar!(u8, "u8"; usize, "usize");
impl_into_r_as_scalar!(u8, "u8"; f32, "f32");
impl_into_r_as_scalar!(u8, "u8"; f64, "f64");
// endregion

// region: Scalar implementations: -> RLogical (R logical)

impl IntoRAs<RLogical> for bool {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<RLogical> for RLogical {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

// Integer to logical: only 0, 1, NA_INTEGER allowed
impl IntoRAs<RLogical> for i32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        match self {
            0 => Ok(false.into_sexp()),
            1 => Ok(true.into_sexp()),
            crate::altrep_traits::NA_INTEGER => Ok(RLogical::NA.into_sexp()),
            _ => Err(StorageCoerceError::OutOfRange {
                from: "i32",
                to: "RLogical",
                index: None,
            }),
        }
    }
}
// endregion

// region: Scalar implementations: -> String (R character)

impl IntoRAs<String> for String {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<String> for &str {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

// Numeric to String: stringify (including NaN/Inf)
impl IntoRAs<String> for f64 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let s = if self.is_nan() {
            "NaN".to_string()
        } else if self.is_infinite() {
            if self.is_sign_positive() {
                "Inf".to_string()
            } else {
                "-Inf".to_string()
            }
        } else {
            self.to_string()
        };
        Ok(s.into_sexp())
    }
}

impl IntoRAs<String> for f32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        <f64 as IntoRAs<String>>::into_r_as(self as f64)
    }
}

impl IntoRAs<String> for i32 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.to_string().into_sexp())
    }
}

impl IntoRAs<String> for i64 {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.to_string().into_sexp())
    }
}

impl IntoRAs<String> for bool {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok((if self { "TRUE" } else { "FALSE" }).into_sexp())
    }
}

impl IntoRAs<String> for RLogical {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let s = match self.to_option_bool() {
            None => "NA",
            Some(true) => "TRUE",
            Some(false) => "FALSE",
        };
        Ok(s.into_sexp())
    }
}
// endregion

// region: Vec implementations: -> i32 (R integer vector)

macro_rules! impl_vec_into_r_as {
    ($target:ty, $target_name:literal; $from:ty, $from_name:literal) => {
        impl IntoRAs<$target> for Vec<$from> {
            fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
                let mut result = Vec::with_capacity(self.len());
                let mut listed: Vec<StorageCoerceError> = Vec::new();
                let mut total = 0usize;
                for (i, val) in self.into_iter().enumerate() {
                    match try_coerce_scalar::<$from, $target>(val, $from_name, $target_name) {
                        Ok(v) => result.push(v),
                        Err(e) => {
                            if listed.len() < BATCHED_ERROR_CAP {
                                listed.push(e.at_index(i));
                            }
                            total += 1;
                        }
                    }
                }
                if total > 0 {
                    return Err(StorageCoerceError::Batched {
                        container: concat!("Vec<", $from_name, ">"),
                        listed,
                        total,
                    });
                }
                Ok(result.into_sexp())
            }
        }

        impl IntoRAs<$target> for &[$from] {
            fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
                let mut result = Vec::with_capacity(self.len());
                let mut listed: Vec<StorageCoerceError> = Vec::new();
                let mut total = 0usize;
                for (i, &val) in self.iter().enumerate() {
                    match try_coerce_scalar::<$from, $target>(val, $from_name, $target_name) {
                        Ok(v) => result.push(v),
                        Err(e) => {
                            if listed.len() < BATCHED_ERROR_CAP {
                                listed.push(e.at_index(i));
                            }
                            total += 1;
                        }
                    }
                }
                if total > 0 {
                    return Err(StorageCoerceError::Batched {
                        container: concat!("&[", $from_name, "]"),
                        listed,
                        total,
                    });
                }
                Ok(result.into_sexp())
            }
        }
    };
}

// Identity (direct copy)
impl IntoRAs<i32> for Vec<i32> {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<i32> for &[i32] {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl_vec_into_r_as!(i32, "i32"; i8, "i8");
impl_vec_into_r_as!(i32, "i32"; i16, "i16");
impl_vec_into_r_as!(i32, "i32"; u8, "u8");
impl_vec_into_r_as!(i32, "i32"; u16, "u16");
impl_vec_into_r_as!(i32, "i32"; i64, "i64");
impl_vec_into_r_as!(i32, "i32"; isize, "isize");
impl_vec_into_r_as!(i32, "i32"; u32, "u32");
impl_vec_into_r_as!(i32, "i32"; u64, "u64");
impl_vec_into_r_as!(i32, "i32"; usize, "usize");
impl_vec_into_r_as!(i32, "i32"; f32, "f32");
impl_vec_into_r_as!(i32, "i32"; f64, "f64");

// Vec<bool> -> i32
impl IntoRAs<i32> for Vec<bool> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let result: Vec<i32> = self.into_iter().map(|b| b as i32).collect();
        Ok(result.into_sexp())
    }
}

impl IntoRAs<i32> for &[bool] {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let result: Vec<i32> = self.iter().map(|&b| b as i32).collect();
        Ok(result.into_sexp())
    }
}
// endregion

// region: Vec implementations: -> f64 (R numeric vector)

// Identity - but check for finite values
impl IntoRAs<f64> for Vec<f64> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, &val) in self.iter().enumerate() {
            if !val.is_finite() {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::NonFinite {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "Vec<f64>",
                listed,
                total,
            });
        }
        Ok(self.into_sexp())
    }
}

impl IntoRAs<f64> for &[f64] {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, &val) in self.iter().enumerate() {
            if !val.is_finite() {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::NonFinite {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "&[f64]",
                listed,
                total,
            });
        }
        Ok(self.into_sexp())
    }
}

// f32 - check finite then widen
impl IntoRAs<f64> for Vec<f32> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut result = Vec::with_capacity(self.len());
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, val) in self.into_iter().enumerate() {
            if !val.is_finite() {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::NonFinite {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            } else {
                result.push(val as f64);
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "Vec<f32>",
                listed,
                total,
            });
        }
        Ok(result.into_sexp())
    }
}

impl IntoRAs<f64> for &[f32] {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut result = Vec::with_capacity(self.len());
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, &val) in self.iter().enumerate() {
            if !val.is_finite() {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::NonFinite {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            } else {
                result.push(val as f64);
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "&[f32]",
                listed,
                total,
            });
        }
        Ok(result.into_sexp())
    }
}

// Small integers - infallible widening
macro_rules! impl_vec_into_r_as_f64_infallible {
    ($from:ty) => {
        impl IntoRAs<f64> for Vec<$from> {
            fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
                let result: Vec<f64> = self.into_iter().map(|v| v as f64).collect();
                Ok(result.into_sexp())
            }
        }

        impl IntoRAs<f64> for &[$from] {
            fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
                let result: Vec<f64> = self.iter().map(|&v| v as f64).collect();
                Ok(result.into_sexp())
            }
        }
    };
}

impl_vec_into_r_as_f64_infallible!(i8);
impl_vec_into_r_as_f64_infallible!(i16);
impl_vec_into_r_as_f64_infallible!(u8);
impl_vec_into_r_as_f64_infallible!(u16);
impl_vec_into_r_as_f64_infallible!(u32);

// i32 -> f64: widening is value-preserving EXCEPT for i32::MIN, which is R's
// NA_integer_ sentinel. Casting it would yield the finite -2147483648.0 and
// silently drop the missing-value semantics, so detect it and error instead.
impl IntoRAs<f64> for Vec<i32> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut result = Vec::with_capacity(self.len());
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, val) in self.into_iter().enumerate() {
            if val == crate::altrep_traits::NA_INTEGER {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::MissingValue {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            } else {
                result.push(val as f64);
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "Vec<i32>",
                listed,
                total,
            });
        }
        Ok(result.into_sexp())
    }
}

impl IntoRAs<f64> for &[i32] {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let mut result = Vec::with_capacity(self.len());
        let mut listed: Vec<StorageCoerceError> = Vec::new();
        let mut total = 0usize;
        for (i, &val) in self.iter().enumerate() {
            if val == crate::altrep_traits::NA_INTEGER {
                if listed.len() < BATCHED_ERROR_CAP {
                    listed.push(StorageCoerceError::MissingValue {
                        to: "f64",
                        index: Some(i),
                    });
                }
                total += 1;
            } else {
                result.push(val as f64);
            }
        }
        if total > 0 {
            return Err(StorageCoerceError::Batched {
                container: "&[i32]",
                listed,
                total,
            });
        }
        Ok(result.into_sexp())
    }
}

// Large integers - check precision
impl_vec_into_r_as!(f64, "f64"; i64, "i64");
impl_vec_into_r_as!(f64, "f64"; u64, "u64");
impl_vec_into_r_as!(f64, "f64"; isize, "isize");
impl_vec_into_r_as!(f64, "f64"; usize, "usize");

// Vec<bool> -> f64
impl IntoRAs<f64> for Vec<bool> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let result: Vec<f64> = self
            .into_iter()
            .map(|b| if b { 1.0 } else { 0.0 })
            .collect();
        Ok(result.into_sexp())
    }
}

impl IntoRAs<f64> for &[bool] {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let result: Vec<f64> = self.iter().map(|&b| if b { 1.0 } else { 0.0 }).collect();
        Ok(result.into_sexp())
    }
}
// endregion

// region: Vec implementations: -> u8 (R raw vector)

// Identity
impl IntoRAs<u8> for Vec<u8> {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<u8> for &[u8] {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl_vec_into_r_as!(u8, "u8"; i8, "i8");
impl_vec_into_r_as!(u8, "u8"; i16, "i16");
impl_vec_into_r_as!(u8, "u8"; i32, "i32");
impl_vec_into_r_as!(u8, "u8"; i64, "i64");
impl_vec_into_r_as!(u8, "u8"; isize, "isize");
impl_vec_into_r_as!(u8, "u8"; u16, "u16");
impl_vec_into_r_as!(u8, "u8"; u32, "u32");
impl_vec_into_r_as!(u8, "u8"; u64, "u64");
impl_vec_into_r_as!(u8, "u8"; usize, "usize");
impl_vec_into_r_as!(u8, "u8"; f32, "f32");
impl_vec_into_r_as!(u8, "u8"; f64, "f64");
// endregion

// region: Vec implementations: -> RLogical (R logical vector)

impl IntoRAs<RLogical> for Vec<bool> {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<RLogical> for &[bool] {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}
// endregion

// region: Vec implementations: -> String (R character vector)

impl IntoRAs<String> for Vec<String> {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<String> for &[String] {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<String> for Vec<&str> {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

impl IntoRAs<String> for &[&str] {
    #[inline]
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        Ok(self.into_sexp())
    }
}

// Numeric vectors to String (stringify)
impl IntoRAs<String> for Vec<f64> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let strings: Vec<String> = self
            .into_iter()
            .map(|v| {
                if v.is_nan() {
                    "NaN".to_string()
                } else if v.is_infinite() {
                    if v.is_sign_positive() {
                        "Inf".to_string()
                    } else {
                        "-Inf".to_string()
                    }
                } else {
                    v.to_string()
                }
            })
            .collect();
        Ok(strings.into_sexp())
    }
}

impl IntoRAs<String> for Vec<i32> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let strings: Vec<String> = self.into_iter().map(|v| v.to_string()).collect();
        Ok(strings.into_sexp())
    }
}

impl IntoRAs<String> for Vec<i64> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let strings: Vec<String> = self.into_iter().map(|v| v.to_string()).collect();
        Ok(strings.into_sexp())
    }
}

impl IntoRAs<String> for Vec<bool> {
    fn into_r_as(self) -> Result<SEXP, StorageCoerceError> {
        let strings: Vec<String> = self
            .into_iter()
            .map(|b| if b { "TRUE" } else { "FALSE" }.to_string())
            .collect();
        Ok(strings.into_sexp())
    }
}
// endregion

// region: Tests

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

    // Note: These are compile-time tests to ensure the trait is implemented correctly.
    // Runtime tests require R to be initialized and should go in the integration tests.

    fn _assert_into_r_as<T, Target>()
    where
        T: IntoRAs<Target>,
    {
    }

    #[test]
    fn test_trait_bounds() {
        // Scalars -> i32
        _assert_into_r_as::<i32, i32>();
        _assert_into_r_as::<i64, i32>();
        _assert_into_r_as::<f64, i32>();
        _assert_into_r_as::<bool, i32>();

        // Scalars -> f64
        _assert_into_r_as::<f64, f64>();
        _assert_into_r_as::<i32, f64>();
        _assert_into_r_as::<i64, f64>();
        _assert_into_r_as::<bool, f64>();

        // Scalars -> u8
        _assert_into_r_as::<u8, u8>();
        _assert_into_r_as::<i32, u8>();

        // Scalars -> RLogical
        _assert_into_r_as::<bool, RLogical>();
        _assert_into_r_as::<i32, RLogical>();

        // Scalars -> String
        _assert_into_r_as::<String, String>();
        _assert_into_r_as::<&str, String>();
        _assert_into_r_as::<f64, String>();
        _assert_into_r_as::<i32, String>();
        _assert_into_r_as::<bool, String>();

        // Vecs -> i32
        _assert_into_r_as::<Vec<i32>, i32>();
        _assert_into_r_as::<Vec<i64>, i32>();
        _assert_into_r_as::<Vec<f64>, i32>();

        // Vecs -> f64
        _assert_into_r_as::<Vec<f64>, f64>();
        _assert_into_r_as::<Vec<i32>, f64>();
        _assert_into_r_as::<Vec<i64>, f64>();

        // Vecs -> u8
        _assert_into_r_as::<Vec<u8>, u8>();
        _assert_into_r_as::<Vec<i32>, u8>();

        // Vecs -> String
        _assert_into_r_as::<Vec<String>, String>();
        _assert_into_r_as::<Vec<f64>, String>();
    }

    // Batched-error tests (#1097). These only exercise the failure path
    // (`into_sexp()` is never reached), so they don't need `with_r_thread` —
    // unlike the success-path integration tests in `conversion_coverage.rs`.

    /// Failures at indices 3, 17, 42 must all be listed in one `Batched`
    /// error's `Display` string, not just the first one.
    #[test]
    fn batched_vec_i64_to_i32_lists_all_failing_indices() {
        let mut v = vec![0i64; 43];
        for &i in &[3usize, 17, 42] {
            v[i] = i64::MAX;
        }
        let result = IntoRAs::<i32>::into_r_as(v);
        match result {
            Err(StorageCoerceError::Batched {
                container,
                listed,
                total,
            }) => {
                assert_eq!(container, "Vec<i64>");
                assert_eq!(total, 3);
                assert_eq!(listed.len(), 3);
                let display = StorageCoerceError::Batched {
                    container,
                    listed,
                    total,
                }
                .to_string();
                assert!(display.contains("index 3"), "{display}");
                assert!(display.contains("index 17"), "{display}");
                assert!(display.contains("index 42"), "{display}");
            }
            other => panic!("expected Batched, got {other:?}"),
        }
    }

    /// A 15-failure input lists only the first `BATCHED_ERROR_CAP` (10) and
    /// summarizes the rest as `"and 5 more"`.
    #[test]
    fn batched_vec_i64_to_i32_caps_listed_and_summarizes_rest() {
        let v = vec![i64::MAX; 15];
        let result = IntoRAs::<i32>::into_r_as(v);
        match result {
            Err(e @ StorageCoerceError::Batched { .. }) => {
                if let StorageCoerceError::Batched { listed, total, .. } = &e {
                    assert_eq!(*total, 15);
                    assert_eq!(listed.len(), BATCHED_ERROR_CAP);
                }
                let display = e.to_string();
                assert!(display.contains("and 5 more"), "{display}");
            }
            other => panic!("expected Batched, got {other:?}"),
        }
    }

    /// The `&[T]` slice arms carry their own container label (`"&[i64]"`,
    /// not `"Vec<i64>"`) and batch failures the same way as the `Vec` arms.
    #[test]
    fn batched_slice_i64_to_i32_lists_all_failing_indices() {
        let mut v = vec![0i64; 6];
        v[1] = i64::MAX;
        v[4] = i64::MIN;
        let result = IntoRAs::<i32>::into_r_as(v.as_slice());
        match result {
            Err(e @ StorageCoerceError::Batched { .. }) => {
                if let StorageCoerceError::Batched {
                    container,
                    listed,
                    total,
                } = &e
                {
                    assert_eq!(*container, "&[i64]");
                    assert_eq!(*total, 2);
                    assert_eq!(listed.len(), 2);
                }
                let display = e.to_string();
                assert!(display.contains("&[i64] conversion failed"), "{display}");
                assert!(display.contains("index 1"), "{display}");
                assert!(display.contains("index 4"), "{display}");
            }
            other => panic!("expected Batched, got {other:?}"),
        }
    }

    /// Scalar conversion failures must keep the plain (non-`Batched`) shape
    /// and Display grammar — only vector conversions batch.
    #[test]
    fn scalar_failure_display_unchanged() {
        let result = IntoRAs::<i32>::into_r_as(i64::MAX);
        match result {
            Err(e @ StorageCoerceError::OutOfRange { .. }) => {
                assert_eq!(e.to_string(), "value out of range for i64 → i32");
            }
            other => panic!("expected scalar OutOfRange, got {other:?}"),
        }
    }
}
// endregion