miniextendr_api/into_r/

large_integers.rs

//! Large integer types → REALSXP (f64).
//!
//! R doesn't have native 64-bit integers. These types convert to f64 (REALSXP)
//! which may lose precision for values outside the "safe integer" range.
//!
//! # Tradeoff
//!
//! These are the **lax** outbound impls — values in `(i32::MIN, i32::MAX]`
//! become `INTSXP` and everything else silently widens to `REALSXP`, with
//! precision loss above `2^53`. The strict alternative is
//! [`crate::strict::checked_into_sexp_i64`] (and the `u64`/`isize`/`usize`
//! siblings), reached via `#[miniextendr(strict)]` — those panic (→ R error)
//! instead of widening. Failure mode of staying on the lax path with
//! IDs/counters: collisions once values exceed `2^53` (≈ `9 × 10^15`).
//!
//! For storage-directed conversions (force `INTSXP`, error if out of range)
//! see [`crate::into_r_as::IntoRAs`].

use crate::altrep_traits::{NA_INTEGER, NA_LOGICAL, NA_REAL};
use crate::into_r::IntoR;
//
// **Precision Loss Warning:**
// - f64 can exactly represent integers in range [-2^53, 2^53] (±9,007,199,254,740,992)
// - Values outside this range may be rounded to the nearest representable f64
// - This is silent - no error or warning is raised
//
// **Alternatives for exact 64-bit integers:**
// - Use the `bit64` R package (stores as REALSXP but interprets as int64)
// - Store as character strings and parse in R
// - Split into high/low 32-bit parts
//
// For most use cases (counters, IDs, timestamps), values fit within 2^53.

/// Convert `i64` to R integer (INTSXP) or numeric (REALSXP).
///
/// Uses smart conversion: values in `(i32::MIN, i32::MAX]` are returned as
/// R integers for exact representation. Values outside that range (including
/// `i32::MIN` which is `NA_integer_` in R) fall back to R doubles.
///
/// ```ignore
/// let small: i64 = 42;
/// small.into_sexp(); // R integer 42L
///
/// let big: i64 = 3_000_000_000;
/// big.into_sexp(); // R double 3e9
///
/// let na_trap: i64 = i32::MIN as i64;
/// na_trap.into_sexp(); // R double (not NA_integer_!)
/// ```
impl IntoR for i64 {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        // i32::MIN is NA_integer_ in R, so exclude it from the integer range
        if self > i32::MIN as i64 && self <= i32::MAX as i64 {
            // Range guard verified — cast is safe
            (self as i32).into_sexp()
        } else {
            // R has no 64-bit integer; f64 loses precision > 2^53
            (self as f64).into_sexp()
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        if self > i32::MIN as i64 && self <= i32::MAX as i64 {
            unsafe { (self as i32).into_sexp_unchecked() }
        } else {
            unsafe { (self as f64).into_sexp_unchecked() }
        }
    }
}

/// Convert `u64` to R integer (INTSXP) or numeric (REALSXP).
///
/// Values in `[0, i32::MAX]` are returned as R integers. Larger values
/// fall back to R doubles (which may lose precision above 2^53).
impl IntoR for u64 {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        if self <= i32::MAX as u64 {
            (self as i32).into_sexp()
        } else {
            (self as f64).into_sexp()
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        if self <= i32::MAX as u64 {
            unsafe { (self as i32).into_sexp_unchecked() }
        } else {
            unsafe { (self as f64).into_sexp_unchecked() }
        }
    }
}

/// Convert `isize` to R integer (INTSXP) or numeric (REALSXP).
///
/// On 64-bit platforms, uses the same smart conversion as [`i64`](impl IntoR for i64).
/// On 32-bit platforms, `isize` fits in i32 so conversion is always exact.
impl IntoR for isize {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok((self as i64).into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        (self as i64).into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { (self as i64).into_sexp_unchecked() }
    }
}

/// Convert `usize` to R integer (INTSXP) or numeric (REALSXP).
///
/// Values in `[0, i32::MAX]` are returned as R integers. Larger values
/// fall back to R doubles.
impl IntoR for usize {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok((self as u64).into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        (self as u64).into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { (self as u64).into_sexp_unchecked() }
    }
}

/// Macro for logical IntoR via Rf_ScalarLogical with conversion to i32.
macro_rules! impl_logical_into_r {
    ($ty:ty, $to_i32:expr) => {
        impl IntoR for $ty {
            type Error = std::convert::Infallible;
            #[inline]
            fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
                Ok(crate::SEXP::scalar_logical_raw($to_i32(self)))
            }
            #[inline]
            unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
                Ok(unsafe { self.into_sexp_unchecked() })
            }
            #[inline]
            fn into_sexp(self) -> crate::SEXP {
                crate::SEXP::scalar_logical_raw($to_i32(self))
            }
            #[inline]
            unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
                unsafe { crate::SEXP::scalar_logical_raw_unchecked($to_i32(self)) }
            }
        }
    };
}

impl_logical_into_r!(bool, |v: bool| i32::from(v));
impl_logical_into_r!(crate::Rboolean, |v: crate::Rboolean| v as i32);
impl_logical_into_r!(crate::RLogical, crate::RLogical::to_i32);

impl IntoR for Option<i32> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Some(v) => v.into_sexp(),
            None => crate::SEXP::scalar_integer(NA_INTEGER),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(v) => unsafe { v.into_sexp_unchecked() },
            None => unsafe { crate::SEXP::scalar_integer_unchecked(NA_INTEGER) },
        }
    }
}

impl IntoR for Option<f64> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Some(v) => v.into_sexp(),
            None => crate::SEXP::scalar_real(NA_REAL),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(v) => unsafe { v.into_sexp_unchecked() },
            None => unsafe { crate::SEXP::scalar_real_unchecked(NA_REAL) },
        }
    }
}

impl IntoR for Option<crate::Rboolean> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            // Rboolean is repr(i32), `as i32` is a no-op transmute
            Some(v) => crate::SEXP::scalar_logical_raw(v as i32),
            None => crate::SEXP::scalar_logical_raw(NA_LOGICAL),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(v) => unsafe { crate::SEXP::scalar_logical_raw_unchecked(v as i32) },
            None => unsafe { crate::SEXP::scalar_logical_raw_unchecked(NA_LOGICAL) },
        }
    }
}

impl IntoR for Option<crate::RLogical> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Some(v) => crate::SEXP::scalar_logical_raw(v.to_i32()),
            None => crate::SEXP::scalar_logical_raw(NA_LOGICAL),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(v) => unsafe { crate::SEXP::scalar_logical_raw_unchecked(v.to_i32()) },
            None => unsafe { crate::SEXP::scalar_logical_raw_unchecked(NA_LOGICAL) },
        }
    }
}

impl IntoR for Option<bool> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Some(v) => v.into_sexp(),
            None => crate::SEXP::scalar_logical_raw(NA_LOGICAL),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(v) => unsafe { v.into_sexp_unchecked() },
            None => unsafe { crate::SEXP::scalar_logical_raw_unchecked(NA_LOGICAL) },
        }
    }
}

/// Macro for NA-aware `Option<T> → R` smart scalar conversion.
/// Checks if value fits i32 → INTSXP with NA_INTEGER for None,
/// otherwise REALSXP with NA_REAL for None.
macro_rules! impl_option_smart_i64_into_r {
    ($t:ty, $fits_i32:expr) => {
        impl IntoR for Option<$t> {
            type Error = std::convert::Infallible;
            #[inline]
            fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
                Ok(self.into_sexp())
            }
            #[inline]
            unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
                self.try_into_sexp()
            }
            #[inline]
            fn into_sexp(self) -> crate::SEXP {
                match self {
                    Some(x) if $fits_i32(x) => (x as i32).into_sexp(),
                    Some(x) => (x as f64).into_sexp(),
                    None => crate::SEXP::scalar_integer(NA_INTEGER),
                }
            }
        }
    };
}

impl_option_smart_i64_into_r!(i64, |x: i64| x > i32::MIN as i64 && x <= i32::MAX as i64);
impl_option_smart_i64_into_r!(u64, |x: u64| x <= i32::MAX as u64);
impl_option_smart_i64_into_r!(isize, |x: isize| x > i32::MIN as isize
    && x <= i32::MAX as isize);
impl_option_smart_i64_into_r!(usize, |x: usize| x <= i32::MAX as usize);

/// Macro for `Option<T>` where `T` coerces to a type with existing Option impl.
macro_rules! impl_option_coerce_into_r {
    ($from:ty => $to:ty) => {
        impl IntoR for Option<$from> {
            type Error = std::convert::Infallible;
            #[inline]
            fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
                Ok(self.map(|x| x as $to).into_sexp())
            }
            #[inline]
            unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
                self.try_into_sexp()
            }
            #[inline]
            fn into_sexp(self) -> crate::SEXP {
                self.map(|x| x as $to).into_sexp()
            }
        }
    };
}

impl_option_coerce_into_r!(i8 => i32);
impl_option_coerce_into_r!(i16 => i32);
impl_option_coerce_into_r!(u16 => i32);
impl_option_coerce_into_r!(u32 => i64); // delegates to smart i64 path
impl_option_coerce_into_r!(f32 => f64);

impl<T: crate::externalptr::TypedExternal> IntoR for crate::externalptr::ExternalPtr<T> {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.as_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.as_sexp())
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        self.as_sexp()
    }
}

/// Build an R list (VECSXP) of external pointers from `Vec<ExternalPtr<T>>`.
///
/// Each element `EXTPTRSXP` is rooted in the process-wide
/// [`ProtectPool`](crate::protect_pool) for the lifetime of its `ExternalPtr`
/// handle (#836/#841), so holding them in a `Vec` is GC-safe and laying them
/// into a freshly allocated list needs no extra protection — see
/// [`vec_externalptr_to_list`].
impl<T: crate::externalptr::TypedExternal> IntoR for Vec<crate::externalptr::ExternalPtr<T>> {
    type Error = std::convert::Infallible;
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
    fn into_sexp(self) -> crate::SEXP {
        vec_externalptr_to_list(self)
    }
}

/// Build an R list (VECSXP) from `Vec<Option<ExternalPtr<T>>>`, with `None`
/// mapping to `NULL` and `Some(ptr)` to the external pointer (issue #827).
impl<T: crate::externalptr::TypedExternal> IntoR
    for Vec<Option<crate::externalptr::ExternalPtr<T>>>
{
    type Error = std::convert::Infallible;
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
    fn into_sexp(self) -> crate::SEXP {
        vec_option_externalptr_to_list(self)
    }
}

/// Allocate a VECSXP and populate it with the external pointers in `items`.
///
/// Each element is rooted in the process-wide [`ProtectPool`] for as long as its
/// `ExternalPtr` handle lives, and `items` owns those handles across the
/// `Rf_allocVector` below — so allocating the list cannot collect them and no
/// pre-protection is required. Storing into the freshly allocated list never
/// allocates, so the list itself stays live until it becomes the `.Call`
/// result, which R protects. (Before #841 the handles were unprotected, which
/// forced a pre-protect of every element here.)
///
/// This receives *already-built* handles, so it can't use the faster
/// [`ExternalPtr::collect_into_r_list`] — that builds fresh `EXTPTRSXP`s from
/// owned `T` values and is the path to prefer when you start from a `Vec<T>`
/// rather than a `Vec<ExternalPtr<T>>`.
///
/// [`ProtectPool`]: crate::protect_pool::ProtectPool
/// [`ExternalPtr::collect_into_r_list`]: crate::externalptr::ExternalPtr::collect_into_r_list
fn vec_externalptr_to_list<T: crate::externalptr::TypedExternal>(
    items: Vec<crate::externalptr::ExternalPtr<T>>,
) -> crate::SEXP {
    use crate::SexpExt;
    // SAFETY: return-value conversion runs on R's main thread (after
    // `run_on_worker` hands the `Vec` back); every element is pool-rooted and
    // kept alive by `items` across the single allocation.
    unsafe {
        let n = items.len();
        let list = crate::sys::Rf_allocVector(crate::SEXPTYPE::VECSXP, n as crate::R_xlen_t);
        for (i, item) in items.iter().enumerate() {
            list.set_vector_elt(i as crate::R_xlen_t, item.as_sexp());
        }
        list
    }
}

/// As [`vec_externalptr_to_list`], but `None` elements become `NULL`.
fn vec_option_externalptr_to_list<T: crate::externalptr::TypedExternal>(
    items: Vec<Option<crate::externalptr::ExternalPtr<T>>>,
) -> crate::SEXP {
    use crate::SexpExt;
    // SAFETY: see `vec_externalptr_to_list` — each `Some` handle is pool-rooted
    // and kept alive by `items` across the allocation; `None` becomes `NULL`.
    unsafe {
        let n = items.len();
        let list = crate::sys::Rf_allocVector(crate::SEXPTYPE::VECSXP, n as crate::R_xlen_t);
        for (i, item) in items.iter().enumerate() {
            let elt = match item {
                Some(ext) => ext.as_sexp(),
                None => crate::SEXP::nil(),
            };
            list.set_vector_elt(i as crate::R_xlen_t, elt);
        }
        list
    }
}

/// Blanket impl: Types marked with `IntoExternalPtr` get automatic `IntoR`.
///
/// This wraps the value in `ExternalPtr<T>` automatically, so you can return
/// `MyType` directly from `#[miniextendr]` functions instead of `ExternalPtr<MyType>`.
impl<T: crate::externalptr::IntoExternalPtr> IntoR for T {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        crate::externalptr::ExternalPtr::new(self).into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { crate::externalptr::ExternalPtr::new_unchecked(self).into_sexp() }
    }
}

/// Helper to convert a string slice to R CHARSXP.
/// Uses UTF-8 encoding. Empty strings return R_BlankString (static, no allocation).
#[inline]
pub(crate) fn str_to_charsxp(s: &str) -> crate::SEXP {
    if s.is_empty() {
        crate::SEXP::blank_string()
    } else {
        let _len: i32 = s.len().try_into().expect("string exceeds i32::MAX bytes");
        crate::SEXP::charsxp(s)
    }
}

/// Unchecked version of [`str_to_charsxp`].
#[inline]
pub(crate) unsafe fn str_to_charsxp_unchecked(s: &str) -> crate::SEXP {
    unsafe {
        if s.is_empty() {
            crate::SEXP::blank_string()
        } else {
            let len: i32 = s.len().try_into().expect("string exceeds i32::MAX bytes");
            crate::sys::Rf_mkCharLenCE_unchecked(s.as_ptr().cast(), len, crate::sexp_types::CE_UTF8)
        }
    }
}

impl IntoR for String {
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        self.as_str().try_into_sexp()
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        self.as_str().into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { self.as_str().into_sexp_unchecked() }
    }
}

impl IntoR for Box<str> {
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        // `String::from(Box<str>)` is O(1) (reuses the allocation); the produced
        // SEXP is identical to the `String` impl's — a `character(1)` STRSXP.
        String::from(self).try_into_sexp()
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        String::from(self).into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { String::from(self).into_sexp_unchecked() }
    }
}

impl IntoR for char {
    type Error = std::convert::Infallible;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        // Convert char to a single-character string — always ≤ 4 bytes, cannot overflow i32
        let mut buf = [0u8; 4];
        let s = self.encode_utf8(&mut buf);
        crate::SEXP::scalar_string(str_to_charsxp(s))
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        let mut buf = [0u8; 4];
        let s = self.encode_utf8(&mut buf);
        unsafe { s.into_sexp_unchecked() }
    }
}

impl IntoR for &str {
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        let _len = i32::try_from(self.len())
            .map_err(|_| crate::into_r_error::IntoRError::StringTooLong { len: self.len() })?;
        Ok(crate::SEXP::scalar_string(str_to_charsxp(self)))
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        crate::SEXP::scalar_string(str_to_charsxp(self))
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let charsxp = str_to_charsxp_unchecked(self);
            crate::SEXP::scalar_string_unchecked(charsxp)
        }
    }
}

/// Convert `Option<&str>` to R: `Some(s)` → character, `None` → `NA_character_`.
///
/// This is a deliberate **exception** to the generic `Option<&T> where T:
/// Copy` blanket impl below (which returns `NULL` for `None`, not NA).
/// `str` is unsized, so it can't satisfy that impl's `Copy` bound —
/// `&str` gets its own hand-written impl here instead, and it's written to
/// mirror `Option<String>`'s NA semantics rather than the reference-type
/// NULL semantics. See the module-level "absence contract" doc on
/// [`crate::into_r`] for the full return-category table.
impl IntoR for Option<&str> {
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        match self {
            Some(s) => {
                let _len = i32::try_from(s.len())
                    .map_err(|_| crate::into_r_error::IntoRError::StringTooLong { len: s.len() })?;
                Ok(crate::SEXP::scalar_string(str_to_charsxp(s)))
            }
            None => Ok(crate::SEXP::scalar_string(crate::SEXP::na_string())),
        }
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        let charsxp = match self {
            Some(s) => str_to_charsxp(s),
            None => crate::SEXP::na_string(),
        };
        crate::SEXP::scalar_string(charsxp)
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let charsxp = match self {
                Some(s) => str_to_charsxp_unchecked(s),
                None => crate::SEXP::na_string(),
            };
            crate::SEXP::scalar_string_unchecked(charsxp)
        }
    }
}

impl IntoR for Option<String> {
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        self.as_deref().try_into_sexp()
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        self.as_deref().into_sexp()
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { self.as_deref().into_sexp_unchecked() }
    }
}

/// Convert `Option<&T>` to R SEXP by copying the value.
///
/// - `Some(&v)` → copies `v` and converts to R
/// - `None` → returns `NULL` (R_NilValue)
///
/// Note: This returns NULL for None, not NA, since there's no reference to return.
/// Use `Option<T>` directly if you want NA semantics for scalar types.
///
/// `T: Copy` excludes `str` (unsized), so `Option<&str>` does **not** go
/// through this impl — see the dedicated `Option<&str>` impl above, which
/// returns `NA_character_` instead of `NULL`.
impl<T> IntoR for Option<&T>
where
    T: Copy + IntoR,
{
    type Error = crate::into_r_error::IntoRError;
    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        match self {
            Some(&v) => v
                .try_into_sexp()
                .map_err(|e| crate::into_r_error::IntoRError::Inner(e.to_string())),
            None => Ok(crate::SEXP::nil()),
        }
    }
    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.into_sexp_unchecked() })
    }
    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Some(&v) => v.into_sexp(),
            None => crate::SEXP::nil(),
        }
    }
    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        match self {
            Some(&v) => unsafe { v.into_sexp_unchecked() },
            None => crate::SEXP::nil(),
        }
    }
}

// endregion