miniextendr_api/

convert.rs

//! Wrapper helpers to force specific `IntoR` representations.
//!
//! This module provides two approaches for controlling how Rust types are converted to R:
//!
//! ## 1. `As*` Wrappers (Call-site Control)
//!
//! Use these wrappers when you want to override the conversion for a single return value:
//!
//! - [`AsList<T>`]: Convert `T` to an R list via [`IntoList`]
//! - [`AsExternalPtr<T>`]: Convert `T` to an R external pointer
//! - [`AsRNative<T>`]: Convert scalar `T` to a length-1 R vector
//!
//! ```ignore
//! #[miniextendr]
//! fn get_data() -> AsList<MyStruct> {
//!     AsList(MyStruct { x: 1, y: 2 })
//! }
//! ```
//!
//! ## 2. `Prefer*` Derive Macros (Type-level Control)
//!
//! Use these derives when a type should *always* use a specific conversion:
//!
//! - `#[derive(IntoList, PreferList)]`: Type always converts to R list
//! - `#[derive(ExternalPtr)]`: Type always converts to external pointer
//!   (`PreferExternalPtr` is for a hand-written `TypedExternal` impl)
//! - `#[derive(RNativeType, PreferRNativeType)]`: Newtype always converts to native R scalar
//!
//! ```ignore
//! #[derive(IntoList, PreferList)]
//! struct Point { x: f64, y: f64 }
//!
//! #[miniextendr]
//! fn make_point() -> Point {  // Automatically becomes R list
//!     Point { x: 1.0, y: 2.0 }
//! }
//! ```
//!
//! ## 3. `#[miniextendr(return = "...")]` Attribute
//!
//! Use this when you want to control conversion for a specific `#[miniextendr]` function
//! without modifying the type itself:
//!
//! - `return = "list"`: Wrap result in `AsList`
//! - `return = "externalptr"`: Wrap result in `AsExternalPtr`
//! - `return = "native"`: Wrap result in `AsRNative`
//!
//! ```ignore
//! #[miniextendr(return = "list")]
//! fn get_as_list() -> MyStruct {
//!     MyStruct { x: 1 }
//! }
//! ```
//!
//! ## Choosing the Right Approach
//!
//! | Situation | Recommended Approach |
//! |-----------|---------------------|
//! | Type should *always* convert one way | `Prefer*` derive |
//! | Override conversion for one function | `As*` wrapper or `return` attribute |
//! | Type has multiple valid representations | Don't use `Prefer*`; use `As*` or `return` |
//!
//! ## A note on the `Collect*` adapters (naming-convention boundary)
//!
//! This module also exposes [`Collect`], [`CollectStrings`], [`CollectNA`], and
//! [`CollectNAInt`]. These are representation-forcing `IntoR` wrappers in the same
//! spirit as the `As*` family, but they deliberately **do not** carry the `As*`
//! prefix. The distinction is structural: the `As*` wrappers wrap a *finished value*
//! `T` and re-route its conversion (`AsList<T>`, `AsExternalPtr<T>`, `AsRNative<T>`),
//! whereas the `Collect*` wrappers wrap an *iterator* `I: ExactSizeIterator` and
//! materialize it directly into a freshly allocated R vector. The `As*`-of-`T` shape
//! ("convert this value *as* a list / pointer / native scalar") does not describe what
//! these do — `Collect` names the operation (drain an iterator into an R vector),
//! which is the more accurate verb. This divergence is intentional and tracked; see
//! the conversion control-surface analysis (`analysis/conversion-control-surface-2026-06-07.md`,
//! §3.4 / §4.5) and issue #871.

/// `IntoR` for `Option<marker>` of a reading marker: `Some` converts the
/// marker, `None` gives `NULL`, as for the other containers. The marker's
/// `Option` `TryFromSexp` reads `NULL` back as `None`.
macro_rules! impl_option_into_r_null {
    ($t:ty) => {
        impl $crate::into_r::IntoR for Option<$t> {
            type Error = <$t as $crate::into_r::IntoR>::Error;
            #[inline]
            fn try_into_sexp(self) -> Result<$crate::SEXP, Self::Error> {
                match self {
                    Some(v) => v.try_into_sexp(),
                    None => Ok($crate::SEXP::nil()),
                }
            }
            #[inline]
            unsafe fn try_into_sexp_unchecked(self) -> Result<$crate::SEXP, Self::Error> {
                match self {
                    Some(v) => unsafe { v.try_into_sexp_unchecked() },
                    None => Ok($crate::SEXP::nil()),
                }
            }
            #[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(),
                }
            }
        }
    };
}

mod as_character;
mod as_numeric;
pub(crate) use as_character::read_character;
pub use as_character::{AsCharacter, AsCharacterVec};
pub use as_numeric::{AsNumeric, AsNumericVec};

use crate::RNativeType;
use crate::externalptr::{ExternalPtr, IntoExternalPtr};
use crate::into_r::IntoR;
use crate::list::{IntoList, List};
use crate::named_vector::AtomicElement;

/// Wrap a value and convert it to an R list via [`IntoList`] when returned from Rust.
///
/// Use this wrapper when you want to convert a single value to an R list without
/// making that the default behavior for the type.
///
/// # Example
///
/// ```ignore
/// #[derive(IntoList)]
/// struct Point { x: f64, y: f64 }
///
/// #[miniextendr]
/// fn make_point() -> AsList<Point> {
///     AsList(Point { x: 1.0, y: 2.0 })
/// }
/// // In R: make_point() returns list(x = 1.0, y = 2.0)
/// ```
#[derive(Debug, Clone, Copy)]
pub struct AsList<T: IntoList>(pub T);

impl<T: IntoList> From<T> for AsList<T> {
    fn from(value: T) -> Self {
        AsList(value)
    }
}

impl<T: IntoList> IntoR for AsList<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 {
        self.0.into_list().into_sexp()
    }
}

// The historical public `convert::IntoDataFrame` (`-> List`) is retired. Its row→List engine
// now lives in `crate::dataframe::ColumnSource` (an internal `#[doc(hidden)]` trait that the
// enum-flatten codegen and the new public `dataframe::IntoDataFrame` both delegate to). The
// public verb surface is `dataframe::{IntoDataFrame, FromDataFrame}` (returning
// `Result<BuiltDataFrame, DataFrameError>`), which mirrors `IntoR` / `TryFromSexp`.
pub use crate::dataframe::ColumnSource;

// region: Column gather/scatter helpers

/// Scatter a typed column SEXP from a dense inner data frame into a new
/// SEXP of length `n_rows`, placing `NA`/`NULL` at rows not in `present_idx`.
///
/// This is called by `DataFrameRow`-derived enum code to flatten struct-typed
/// variant fields into prefixed columns of the parent data frame.
///
/// The output type mirrors the input:
/// - REALSXP → REALSXP (NA_real_ fill)
/// - INTSXP  → INTSXP  (NA_integer_ fill)
/// - LGLSXP  → LGLSXP  (NA_logical fill)
/// - RAWSXP  → RAWSXP  (`0x00` fill — R raw has no NA)
/// - CPLXSXP → CPLXSXP (NA complex fill: both parts NA_real_)
/// - STRSXP  → STRSXP  (NA_character_ fill)
/// - VECSXP  → VECSXP  (R_NilValue fill)
/// - anything else → VECSXP (R_NilValue fill)
///
/// Contiguous primitive columns (real/integer/logical/raw/complex) scatter as a
/// flat slice write via [`scatter_native`] — the NA-filled inverse of
/// [`gather_native`]. String and list columns stay element-by-element because
/// they are write-barriered arrays of `SEXP` pointers, not flat buffers.
///
/// When the output type mirrors the input, the column keeps every attribute
/// except names/dim/dimnames, as `DataFrame::select_rows` does on the way back:
/// a factor keeps its `levels` and `class` (absent rows are `NA`), a `Date` or
/// `POSIXct` column its `class` and `tzone`.
///
/// # Safety
///
/// Must be called on the R main thread. `src` must be a valid SEXP of length
/// `>= present_idx.len()`, kept reachable by the caller across this call.
/// `n_rows` must equal the total row count of the parent data frame.
#[doc(hidden)]
pub unsafe fn scatter_column(
    src: crate::SEXP,
    present_idx: &[usize],
    n_rows: usize,
) -> crate::SEXP {
    // SAFETY: caller guarantees R main thread; src is valid; n_rows is correct.
    #[allow(unused_unsafe)]
    unsafe {
        use crate::{RLogical, Rcomplex, SEXPTYPE, SexpExt as _};

        let out = match src.type_of() {
            SEXPTYPE::REALSXP => scatter_native::<f64>(src, present_idx, n_rows),
            SEXPTYPE::INTSXP => scatter_native::<i32>(src, present_idx, n_rows),
            SEXPTYPE::LGLSXP => scatter_native::<RLogical>(src, present_idx, n_rows),
            SEXPTYPE::RAWSXP => scatter_native::<u8>(src, present_idx, n_rows),
            SEXPTYPE::CPLXSXP => scatter_native::<Rcomplex>(src, present_idx, n_rows),
            SEXPTYPE::STRSXP => {
                let out = crate::sys::Rf_allocVector(SEXPTYPE::STRSXP, n_rows as isize);
                // Write-barriered CHARSXP-pointer array — fill NA_character_, then
                // scatter present cells element-by-element.
                for i in 0..(n_rows as isize) {
                    out.set_string_elt(i, crate::SEXP::na_string());
                }
                for (pi, &row_i) in present_idx.iter().enumerate() {
                    out.set_string_elt(row_i as isize, src.string_elt(pi as isize));
                }
                out
            }
            SEXPTYPE::VECSXP => {
                let out = crate::sys::Rf_allocVector(SEXPTYPE::VECSXP, n_rows as isize);
                // Write-barriered SEXP-pointer array. R_NilValue fill is automatic
                // (Rf_allocVector zero-initialises VECSXP slots).
                for (pi, &row_i) in present_idx.iter().enumerate() {
                    out.set_vector_elt(row_i as isize, src.vector_elt(pi as isize));
                }
                out
            }
            _ => {
                // Unknown/unsupported type — produce a VECSXP list-column.
                // Cells for absent rows remain R_NilValue.
                let out = crate::sys::Rf_allocVector(SEXPTYPE::VECSXP, n_rows as isize);
                for (pi, &row_i) in present_idx.iter().enumerate() {
                    out.set_vector_elt(row_i as isize, src.vector_elt(pi as isize));
                }
                return out;
            }
        };
        // Copying the attributes allocates, so root `out` until it returns.
        let out = crate::OwnedProtect::new(out);
        out.copy_most_attrib(src);
        *out
    }
}

/// Scatter a dense typed column into a fresh SEXP of length `n_rows`, placing the
/// `j`-th source value at row `present_idx[j]` and the per-type NA sentinel
/// ([`RNativeType::R_NA`]) at every absent row.
///
/// The sparse-placing inverse of [`gather_native`]. Generic over the R element
/// type: `f64`/`i32`/`RLogical`/`u8`/`Rcomplex` each resolve to the correct
/// storage via their `RNativeType` impl, so the whole copy is a flat slice write
/// with no per-element FFI call. Raw (`u8`) has no R NA, so absent positions
/// become `0x00`.
///
/// # Safety
///
/// R main thread; `src` must be a `T::SEXP_TYPE` vector with at least
/// `present_idx.len()` elements, and every index in `present_idx` must be
/// `< n_rows`. The returned SEXP is unprotected (see [`scatter_column`]). No
/// allocation occurs between allocating `out` and filling it, so `out` cannot be
/// reaped mid-scatter.
#[inline]
unsafe fn scatter_native<T: RNativeType + Copy>(
    src: crate::SEXP,
    present_idx: &[usize],
    n_rows: usize,
) -> crate::SEXP {
    unsafe {
        use crate::SexpExt as _;
        let src_vals: &[T] = src.as_slice::<T>();
        let out = crate::sys::Rf_allocVector(T::SEXP_TYPE, n_rows as isize);
        let out_vals: &mut [T] = out.as_mut_slice::<T>();
        // NA-fill the whole output, then place present values. No allocation
        // between alloc and fill — `out` is GC-safe.
        out_vals.fill(T::R_NA);
        for (pi, &row_i) in present_idx.iter().enumerate() {
            out_vals[row_i] = src_vals[pi];
        }
        out
    }
}

/// Gather the rows at `idx` (0-based, in order) from a contiguous primitive
/// column into a fresh dense vector, where `out[j] = src[idx[j]]`.
///
/// Generic over the R element type: `f64`/`i32`/`RLogical`/`u8`/`Rcomplex` each
/// resolve to the correct `REAL`/`INTEGER`/`LOGICAL`/`RAW`/`COMPLEX` storage via
/// their `RNativeType` impl, so the copy is a plain slice gather with no
/// per-element FFI call.
///
/// # Safety
///
/// R main thread; `src` must be a `T::SEXP_TYPE` vector and every index in `idx`
/// must be `< xlength(src)`. The returned SEXP is unprotected (see
/// [`gather_column`]). No allocation occurs between allocating `out` and filling
/// it, so `out` cannot be reaped mid-gather.
#[inline]
unsafe fn gather_native<T: RNativeType + Copy>(src: crate::SEXP, idx: &[usize]) -> crate::SEXP {
    unsafe {
        use crate::SexpExt as _;
        let src_vals: &[T] = src.as_slice::<T>();
        let out = crate::sys::Rf_allocVector(T::SEXP_TYPE, idx.len() as isize);
        let out_vals: &mut [T] = out.as_mut_slice::<T>();
        for (dst, &row_i) in out_vals.iter_mut().zip(idx) {
            *dst = src_vals[row_i];
        }
        out
    }
}

/// Gather the elements at `idx` (0-based, in order) out of a typed vector SEXP
/// into a new dense SEXP of length `idx.len()`, where `out[j] = src[idx[j]]`.
///
/// The selecting inverse of [`scatter_column`]: where `scatter_column` places a
/// dense column's values at sparse positions, `gather_column` pulls a dense
/// subset out of a vector by element index. An element is a row only for a
/// plain vector or list column: `DataFrame::select_rows` expands a row index to
/// the element indices of every matrix column and recurses into data.frame
/// columns before calling this.
///
/// Contiguous primitive columns (real/integer/logical/raw/complex) are copied as
/// a slice gather via [`gather_native`]; string and list columns are copied
/// element-by-element because they are write-barriered arrays of `SEXP` pointers,
/// not flat buffers. The output type mirrors the input; any other type falls back
/// to a logical `NA` column (normal `data.frame` columns never reach it).
///
/// Column attributes (`class`, `levels`, `tzone`, element `names`, …) are **not**
/// copied — the caller restores them after rooting the gathered column
/// (`DataFrame::select_rows` uses [`SexpExt::copy_most_attrib`](crate::SexpExt::copy_most_attrib)
/// plus a names gather).
///
/// # Safety
///
/// Must be called on the R main thread. `src` must be a valid SEXP and every
/// index in `idx` must be `< xlength(src)`. The returned SEXP is unprotected;
/// the caller must root it (e.g. via `SET_VECTOR_ELT` into a protected list)
/// before performing any allocation.
#[doc(hidden)]
pub unsafe fn gather_column(src: crate::SEXP, idx: &[usize]) -> crate::SEXP {
    // SAFETY: caller guarantees R main thread, a valid `src`, and in-range indices.
    #[allow(unused_unsafe)]
    unsafe {
        use crate::{RLogical, Rcomplex, SEXPTYPE, SexpExt as _};

        match src.type_of() {
            SEXPTYPE::REALSXP => gather_native::<f64>(src, idx),
            SEXPTYPE::INTSXP => gather_native::<i32>(src, idx),
            SEXPTYPE::LGLSXP => gather_native::<RLogical>(src, idx),
            SEXPTYPE::RAWSXP => gather_native::<u8>(src, idx),
            SEXPTYPE::CPLXSXP => gather_native::<Rcomplex>(src, idx),
            SEXPTYPE::STRSXP => {
                // Write-barriered CHARSXP-pointer array — copy element-by-element.
                let out = crate::sys::Rf_allocVector(SEXPTYPE::STRSXP, idx.len() as isize);
                for (j, &row_i) in idx.iter().enumerate() {
                    out.set_string_elt(j as isize, src.string_elt(row_i as isize));
                }
                out
            }
            SEXPTYPE::VECSXP => {
                // Write-barriered SEXP-pointer array (list-column) — element-by-element.
                let out = crate::sys::Rf_allocVector(SEXPTYPE::VECSXP, idx.len() as isize);
                for (j, &row_i) in idx.iter().enumerate() {
                    out.set_vector_elt(j as isize, src.vector_elt(row_i as isize));
                }
                out
            }
            _ => {
                // Unknown SEXPTYPE: fall back to a logical NA column of the right length.
                let out = crate::sys::Rf_allocVector(SEXPTYPE::LGLSXP, idx.len() as isize);
                let na_vals: &mut [RLogical] = out.as_mut_slice::<RLogical>();
                na_vals.fill(RLogical::NA);
                out
            }
        }
    }
}
// endregion

/// Wrap a value and convert it to an R external pointer when returned from Rust.
///
/// Use this wrapper when you want to return a Rust value as an opaque pointer
/// that R code can pass back to Rust functions later.
///
/// # Example
///
/// ```ignore
/// struct Connection { handle: u64 }
///
/// impl IntoExternalPtr for Connection { /* ... */ }
///
/// #[miniextendr]
/// fn open_connection(path: &str) -> AsExternalPtr<Connection> {
///     AsExternalPtr(Connection { handle: 42 })
/// }
/// // In R: open_connection("foo") returns an external pointer
/// ```
#[derive(Debug, Clone, Copy)]
pub struct AsExternalPtr<T: IntoExternalPtr>(pub T);

impl<T: IntoExternalPtr> From<T> for AsExternalPtr<T> {
    fn from(value: T) -> Self {
        AsExternalPtr(value)
    }
}

impl<T: IntoExternalPtr> IntoR for AsExternalPtr<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 {
        ExternalPtr::new(self.0).into_sexp()
    }
}

/// Wrap a scalar [`RNativeType`] and force native R vector conversion.
///
/// This creates a length-1 R vector containing the scalar value. Use this when
/// you want to ensure a value is converted to its native R representation (e.g.,
/// `i32` → integer vector, `f64` → numeric vector) rather than another path
/// like `IntoExternalPtr`.
///
/// # Example
///
/// ```ignore
/// #[repr(transparent)]
/// #[derive(Clone, Copy, RNativeType)]
/// struct Meters(f64);
///
/// #[miniextendr]
/// fn distance() -> AsRNative<Meters> {
///     AsRNative(Meters(42.5))
/// }
/// // In R: distance() returns 42.5 (numeric vector of length 1)
/// ```
///
/// # Performance
///
/// This wrapper directly allocates an R vector and writes the value,
/// avoiding intermediate Rust allocations.
#[derive(Debug, Clone, Copy)]
pub struct AsRNative<T: RNativeType>(pub T);

impl<T: RNativeType> From<T> for AsRNative<T> {
    fn from(value: T) -> Self {
        AsRNative(value)
    }
}

impl<T: RNativeType> IntoR for AsRNative<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 {
        // Directly allocate a length-1 R vector and write the scalar value.
        // This avoids the intermediate Rust Vec allocation.
        unsafe {
            let sexp = crate::sys::Rf_allocVector(T::SEXP_TYPE, 1);
            let ptr = T::dataptr_mut(sexp);
            std::ptr::write(ptr, self.0);
            sexp
        }
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let sexp = crate::sys::Rf_allocVector_unchecked(T::SEXP_TYPE, 1);
            let ptr = T::dataptr_mut(sexp);
            std::ptr::write(ptr, self.0);
            sexp
        }
    }
}
// endregion

// region: DataFrame / Vctrs representation wrappers

/// Wrap a value and convert it to an R `data.frame` via [`IntoDataFrame`](crate::dataframe::IntoDataFrame) when returned.
///
/// The inner `T` is typically a `Vec<Row>` where `Row` derives
/// [`DataFrameRow`](crate::markers::DataFrameRow). To return a frame directly,
/// return the generated `{Row}DataFrame` companion or build a
/// [`BuiltDataFrame`](crate::dataframe::BuiltDataFrame) with `IntoDataFrame`.
///
/// A failed conversion ([`DataFrameError`](crate::dataframe::DataFrameError)) surfaces in R as
/// an error condition.
///
/// # Example
///
/// ```ignore
/// #[derive(DataFrameRow)]
/// struct Point { x: f64, y: f64 }
///
/// #[miniextendr]
/// fn grid() -> AsDataFrame<Vec<Point>> {
///     AsDataFrame(vec![Point { x: 0.0, y: 0.0 }, Point { x: 1.0, y: 1.0 }])
/// }
/// // In R: grid() returns a data.frame with columns x, y
/// ```
#[derive(Debug, Clone)]
pub struct AsDataFrame<T: crate::dataframe::IntoDataFrame>(pub T);

impl<T: crate::dataframe::IntoDataFrame> From<T> for AsDataFrame<T> {
    fn from(value: T) -> Self {
        AsDataFrame(value)
    }
}

impl<T: crate::dataframe::IntoDataFrame> IntoR for AsDataFrame<T> {
    type Error = crate::dataframe::DataFrameError;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.0.into_dataframe()?.into_sexp())
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
}

/// Wrap a value and convert it to a **vctrs** S3 vector via [`IntoVctrs`](crate::vctrs::IntoVctrs)
/// when returned.
///
/// Use this at a call site to return a `#[derive(Vctrs)]` type as its R vctrs object without the
/// manual `value.into_vctrs().map_err(...)` boilerplate. For a type that should *always* convert
/// this way, use `#[derive(Vctrs, PreferVctrs)]` instead.
///
/// A failed build ([`VctrsBuildError`](crate::vctrs::VctrsBuildError)) surfaces in R as an error
/// condition.
///
/// # Example
///
/// ```ignore
/// #[derive(Vctrs)]
/// #[vctrs(class = "percent", base = "double")]
/// struct Percent { #[vctrs(data)] values: Vec<f64> }
///
/// #[miniextendr]
/// fn percent(x: Vec<f64>) -> AsVctrs<Percent> {
///     AsVctrs(Percent { values: x })
/// }
/// ```
#[cfg(feature = "vctrs")]
#[derive(Debug, Clone)]
pub struct AsVctrs<T: crate::vctrs::IntoVctrs>(pub T);

#[cfg(feature = "vctrs")]
impl<T: crate::vctrs::IntoVctrs> From<T> for AsVctrs<T> {
    fn from(value: T) -> Self {
        AsVctrs(value)
    }
}

#[cfg(feature = "vctrs")]
impl<T: crate::vctrs::IntoVctrs> IntoR for AsVctrs<T> {
    type Error = crate::vctrs::VctrsBuildError;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        self.0.into_vctrs()
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
}
// endregion

// region: Named pair wrappers

/// Wrap a tuple pair collection and convert it to a **named R list** (VECSXP).
///
/// Preserves insertion order and allows duplicate names (sequence semantics).
///
/// # Supported input types
///
/// | Input | Bounds |
/// |-------|--------|
/// | `Vec<(K, V)>` | `K: AsRef<str>`, `V: IntoR` |
/// | `[(K, V); N]` | `K: AsRef<str>`, `V: IntoR` |
/// | `&[(K, V)]` | `K: AsRef<str>`, `V: Clone + IntoR` |
///
/// # GC safety — use *typed* values, never raw `SEXP` (#1030)
///
/// Prefer typed value types (`i32`, `String`, `Vec<T>`, …) over raw
/// [`crate::SEXP`]. With a typed `V`, each value's `into_sexp()` runs *inside*
/// [`AsNamedList::into_sexp`][IntoR::into_sexp], immediately before the value is
/// protected and placed into the list — no allocation ever fires while a sibling
/// value sits unprotected.
///
/// A raw `SEXP` value (`V = SEXP`) is **GC-fragile and must not be used**. The
/// caller has to build the `SEXP` values *in an earlier frame* (each `into_sexp()`
/// allocates) and then hand them to `AsNamedList`; the deferred `from_raw_pairs`
/// runs later, in the generated wrapper, so there is **no call site at which a
/// `ProtectScope` can span both value construction and the deferred list build**.
/// The internal protection added in `into_sexp` (below) closes the *receipt →
/// `from_raw_pairs`* window but cannot retroactively protect values that were
/// already built and unrooted in the caller — that *construction* window is the
/// latent use-after-free. Stable Rust cannot exclude one concrete type from a
/// `V: IntoR` blanket, so this is enforced by convention (and the MXL302 lint on
/// the `into_sexp()`-in-`vec!` idiom) rather than the type system; passing typed
/// values sidesteps the hazard entirely.
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn make_config() -> AsNamedList<Vec<(String, i32)>> {
///     AsNamedList(vec![
///         ("width".into(), 100),
///         ("height".into(), 200),
///     ])
/// }
/// // In R: make_config() returns list(width = 100L, height = 200L)
/// ```
#[derive(Debug, Clone)]
pub struct AsNamedList<T>(pub T);

impl<T> From<T> for AsNamedList<T> {
    fn from(value: T) -> Self {
        AsNamedList(value)
    }
}

impl<K: AsRef<str>, V: IntoR> IntoR for AsNamedList<Vec<(K, V)>> {
    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 {
        // SAFETY: `into_sexp` for `#[miniextendr]` return values runs on the R
        // main thread. Each value's `into_sexp()` is built and immediately
        // `protect_raw`-rooted before the next value's allocation, mirroring the
        // `#[derive(IntoList)]` codegen — no sibling sits unprotected across an
        // allocation. The scope drops after `from_raw_pairs` returns. (#1030)
        unsafe {
            let scope = crate::gc_protect::ProtectScope::new();
            let pairs: Vec<(K, crate::SEXP)> = self
                .0
                .into_iter()
                .map(|(k, v)| (k, scope.protect_raw(v.into_sexp())))
                .collect();
            List::from_raw_pairs(pairs).into_sexp()
        }
    }
}

impl<K: AsRef<str>, V: IntoR, const N: usize> IntoR for AsNamedList<[(K, V); N]> {
    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 {
        // SAFETY: see the `Vec<(K, V)>` impl above — main thread, each value
        // rooted before the next allocates. (#1030)
        unsafe {
            let scope = crate::gc_protect::ProtectScope::new();
            let pairs: Vec<(K, crate::SEXP)> = self
                .0
                .into_iter()
                .map(|(k, v)| (k, scope.protect_raw(v.into_sexp())))
                .collect();
            List::from_raw_pairs(pairs).into_sexp()
        }
    }
}

impl<K: AsRef<str>, V: Clone + IntoR> IntoR for AsNamedList<&[(K, V)]> {
    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 {
        // SAFETY: see the `Vec<(K, V)>` impl above — main thread, each value
        // rooted before the next allocates. (#1030)
        unsafe {
            let scope = crate::gc_protect::ProtectScope::new();
            let pairs: Vec<(&K, crate::SEXP)> = self
                .0
                .iter()
                .map(|(k, v)| (k, scope.protect_raw(v.clone().into_sexp())))
                .collect();
            List::from_raw_pairs(pairs).into_sexp()
        }
    }
}

/// Wrap a tuple pair collection and convert it to a **named atomic R vector**
/// (INTSXP, REALSXP, LGLSXP, RAWSXP, or STRSXP).
///
/// Preserves insertion order and allows duplicate names (sequence semantics).
/// Values must be homogeneous and implement [`AtomicElement`].
///
/// # Supported input types
///
/// | Input | Bounds |
/// |-------|--------|
/// | `Vec<(K, V)>` | `K: AsRef<str>`, `V: AtomicElement` |
/// | `[(K, V); N]` | `K: AsRef<str>`, `V: AtomicElement` |
/// | `&[(K, V)]` | `K: AsRef<str>`, `V: Clone + AtomicElement` |
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn make_scores() -> AsNamedVector<Vec<(&str, f64)>> {
///     AsNamedVector(vec![("alice", 95.0), ("bob", 87.5)])
/// }
/// // In R: make_scores() returns c(alice = 95.0, bob = 87.5)
/// ```
#[derive(Debug, Clone)]
pub struct AsNamedVector<T>(pub T);

impl<T> From<T> for AsNamedVector<T> {
    fn from(value: T) -> Self {
        AsNamedVector(value)
    }
}

impl<K: AsRef<str>, V: AtomicElement> IntoR for AsNamedVector<Vec<(K, V)>> {
    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 {
        named_vector_from_pairs(self.0)
    }
}

impl<K: AsRef<str>, V: AtomicElement, const N: usize> IntoR for AsNamedVector<[(K, V); N]> {
    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 {
        named_vector_from_pairs(self.0)
    }
}

impl<K: AsRef<str>, V: Clone + AtomicElement> IntoR for AsNamedVector<&[(K, V)]> {
    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 {
        let (keys, values): (Vec<&K>, Vec<V>) = self.0.iter().map(|(k, v)| (k, v.clone())).unzip();
        let sexp = V::vec_to_sexp(values);
        unsafe {
            let _guard = crate::OwnedProtect::new(sexp);
            crate::named_vector::set_names_on_sexp(sexp, &keys);
        }
        sexp
    }
}

/// Shared helper: build a named atomic vector from an owning iterator of (key, value) pairs.
fn named_vector_from_pairs<K, V>(pairs: impl IntoIterator<Item = (K, V)>) -> crate::SEXP
where
    K: AsRef<str>,
    V: AtomicElement,
{
    let (keys, values): (Vec<K>, Vec<V>) = pairs.into_iter().unzip();
    let sexp = V::vec_to_sexp(values);
    unsafe {
        let _guard = crate::OwnedProtect::new(sexp);
        crate::named_vector::set_names_on_sexp(sexp, &keys);
    }
    sexp
}
// endregion

// region: Extension traits for ergonomic wrapping
//
// These extension traits provide method-style wrapping that works even when
// the destination type isn't constrained (i.e., `value.wrap_list()` instead
// of `value.into()` which requires type inference).
//
// ```ignore
// // These all work without type annotations:
// let wrapped = my_struct.wrap_list();
// let ptr = my_value.wrap_external_ptr();
// let native = my_num.wrap_r_native();
// ```

/// Extension trait for wrapping values as [`AsList`].
///
/// This trait is automatically implemented for all types that implement [`IntoList`].
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::convert::AsListExt;
///
/// #[derive(IntoList)]
/// struct Point { x: f64, y: f64 }
///
/// let point = Point { x: 1.0, y: 2.0 };
/// let wrapped: AsList<Point> = point.wrap_list();
/// ```
pub trait AsListExt: IntoList + Sized {
    /// Wrap `self` in [`AsList`] for R list conversion.
    fn wrap_list(self) -> AsList<Self> {
        AsList(self)
    }
}

impl<T: IntoList> AsListExt for T {}

/// Extension trait for wrapping values as [`AsExternalPtr`].
///
/// This trait is automatically implemented for all types that implement [`IntoExternalPtr`].
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::convert::AsExternalPtrExt;
///
/// #[derive(ExternalPtr)]
/// struct Connection { handle: u64 }
///
/// let conn = Connection { handle: 42 };
/// let wrapped: AsExternalPtr<Connection> = conn.wrap_external_ptr();
/// ```
pub trait AsExternalPtrExt: IntoExternalPtr + Sized {
    /// Wrap `self` in [`AsExternalPtr`] for R external pointer conversion.
    fn wrap_external_ptr(self) -> AsExternalPtr<Self> {
        AsExternalPtr(self)
    }
}

impl<T: IntoExternalPtr> AsExternalPtrExt for T {}

/// Extension trait for wrapping values as [`AsRNative`].
///
/// This trait is automatically implemented for all types that implement [`RNativeType`].
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::convert::AsRNativeExt;
///
/// let x: f64 = 42.5;
/// let wrapped: AsRNative<f64> = x.wrap_r_native();
/// ```
pub trait AsRNativeExt: RNativeType + Sized {
    /// Wrap `self` in [`AsRNative`] for native R scalar conversion.
    fn wrap_r_native(self) -> AsRNative<Self> {
        AsRNative(self)
    }
}

impl<T: RNativeType> AsRNativeExt for T {}

/// Extension trait for wrapping values as [`AsDataFrame`].
///
/// Automatically implemented for all `T: IntoDataFrame` (typically `Vec<Row>` where `Row`
/// derives `DataFrameRow`).
pub trait AsDataFrameExt: crate::dataframe::IntoDataFrame + Sized {
    /// Wrap `self` in [`AsDataFrame`] for R data.frame conversion.
    fn wrap_data_frame(self) -> AsDataFrame<Self> {
        AsDataFrame(self)
    }
}

impl<T: crate::dataframe::IntoDataFrame> AsDataFrameExt for T {}

/// Extension trait for wrapping values as [`AsVctrs`].
///
/// Automatically implemented for all `T: IntoVctrs` (typically a `#[derive(Vctrs)]` type).
#[cfg(feature = "vctrs")]
pub trait AsVctrsExt: crate::vctrs::IntoVctrs + Sized {
    /// Wrap `self` in [`AsVctrs`] for R vctrs conversion.
    fn wrap_vctrs(self) -> AsVctrs<Self> {
        AsVctrs(self)
    }
}

#[cfg(feature = "vctrs")]
impl<T: crate::vctrs::IntoVctrs> AsVctrsExt for T {}

/// Extension trait for wrapping tuple pair collections as [`AsNamedList`].
///
/// # Example
///
/// ```ignore
/// let pairs = vec![("x".to_string(), 1i32), ("y".to_string(), 2i32)];
/// let wrapped = pairs.wrap_named_list();
/// ```
pub trait AsNamedListExt: Sized {
    /// Wrap `self` in [`AsNamedList`] for named R list conversion.
    fn wrap_named_list(self) -> AsNamedList<Self> {
        AsNamedList(self)
    }
}

impl<K: AsRef<str>, V: IntoR> AsNamedListExt for Vec<(K, V)> {}
impl<K: AsRef<str>, V: IntoR, const N: usize> AsNamedListExt for [(K, V); N] {}
impl<K: AsRef<str>, V: Clone + IntoR> AsNamedListExt for &[(K, V)] {}

/// Extension trait for wrapping tuple pair collections as [`AsNamedVector`].
///
/// # Example
///
/// ```ignore
/// let pairs = vec![("alice".to_string(), 95.0f64), ("bob".to_string(), 87.5)];
/// let wrapped = pairs.wrap_named_vector();
/// ```
pub trait AsNamedVectorExt: Sized {
    /// Wrap `self` in [`AsNamedVector`] for named atomic R vector conversion.
    fn wrap_named_vector(self) -> AsNamedVector<Self> {
        AsNamedVector(self)
    }
}

impl<K: AsRef<str>, V: AtomicElement> AsNamedVectorExt for Vec<(K, V)> {}
impl<K: AsRef<str>, V: AtomicElement, const N: usize> AsNamedVectorExt for [(K, V); N] {}
impl<K: AsRef<str>, V: Clone + AtomicElement> AsNamedVectorExt for &[(K, V)] {}
// endregion

// region: Display/FromStr trait adapters

/// Wrap a `T: Display` and convert it to an R character scalar.
///
/// Any type implementing `std::fmt::Display` can be returned to R as a string
/// without implementing miniextendr traits.
///
/// # Example
///
/// ```ignore
/// use std::net::IpAddr;
///
/// #[miniextendr]
/// fn format_ip(ip: &str) -> AsDisplay<IpAddr> {
///     AsDisplay(ip.parse().unwrap())
/// }
/// // R gets: "192.168.1.1"
/// ```
#[derive(Debug, Clone, Copy)]
pub struct AsDisplay<T>(pub T);

impl<T: std::fmt::Display> IntoR for AsDisplay<T> {
    type Error = std::convert::Infallible;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.0.to_string().into_sexp())
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        Ok(unsafe { self.0.to_string().into_sexp_unchecked() })
    }
}

/// Wrap a `Vec<T: Display>` and convert it to an R character vector.
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn format_errors(errors: Vec<std::io::Error>) -> AsDisplayVec<std::io::Error> {
///     AsDisplayVec(errors)
/// }
/// ```
#[derive(Debug, Clone)]
pub struct AsDisplayVec<T>(pub Vec<T>);

impl<T: std::fmt::Display> IntoR for AsDisplayVec<T> {
    type Error = std::convert::Infallible;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        let strings: Vec<String> = self.0.into_iter().map(|x| x.to_string()).collect();
        Ok(strings.into_sexp())
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        let strings: Vec<String> = self.0.into_iter().map(|x| x.to_string()).collect();
        Ok(unsafe { strings.into_sexp_unchecked() })
    }
}

/// Wrap a parsed `T: FromStr` from an R character scalar.
///
/// Pass an R character scalar and it will be parsed into `T` via `str::parse()`.
/// `NA_character_` is refused with [`SexpError::Na`](crate::from_r::SexpError::Na)
/// rather than parsed as `""`. A parse failure quotes the value:
/// `"not-an-ip": invalid IP address syntax`.
///
/// For numbers read like R's `as.numeric()` (from character, factor labels, or
/// numbers, with `NA` as `None`), use [`AsNumeric`] instead.
///
/// # Example
///
/// ```ignore
/// use std::net::IpAddr;
///
/// #[miniextendr]
/// fn check_ip(addr: AsFromStr<IpAddr>) -> bool {
///     addr.0.is_loopback()
/// }
/// // R: check_ip("127.0.0.1") → TRUE
/// ```
#[derive(Debug, Clone)]
pub struct AsFromStr<T>(pub T);

impl<T: std::str::FromStr> crate::from_r::TryFromSexp for AsFromStr<T>
where
    T::Err: std::fmt::Display,
{
    type Error = crate::from_r::SexpError;
    const CHARACTER_ONLY: bool = true;

    fn try_from_sexp(sexp: crate::SEXP) -> Result<Self, Self::Error> {
        let charsxp = crate::from_r::scalar_charsxp(sexp)?;
        if charsxp == crate::SEXP::na_string() {
            return Err(crate::from_r::SexpNaError {
                sexp_type: crate::SEXPTYPE::STRSXP,
            }
            .into());
        }
        // SAFETY: a non-NA CHARSXP from a live STRSXP argument.
        let s = unsafe { crate::from_r::charsxp_to_str(charsxp) };
        s.parse::<T>()
            .map(AsFromStr)
            .map_err(|e| crate::from_r::SexpError::InvalidValue(format!("{s:?}: {e}")))
    }
}

/// The value's `Display` text as a character scalar, which the marker parses
/// back. A trait's View passes an `AsFromStr` argument this way, so the value
/// crosses unchanged when `T::from_str(&t.to_string()) == t` (the std
/// numbers, `IpAddr`, `Uuid`, ...). This `IntoR` exists for the trait ABI; to
/// return text from a function, use [`AsDisplay`].
impl<T: std::fmt::Display> IntoR for AsFromStr<T> {
    type Error = <String as IntoR>::Error;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        self.0.to_string().try_into_sexp()
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        unsafe { self.0.to_string().try_into_sexp_unchecked() }
    }

    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        self.0.to_string().into_sexp()
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { self.0.to_string().into_sexp_unchecked() }
    }
}

/// Wrap a `Vec<T: FromStr>` parsed from an R character vector.
///
/// Each element of the R character vector is parsed into `T`. Every failure is
/// collected into one error (the first 10 listed, then `"and N more"`), each
/// with its quoted value and 1-based position (`"n/a": invalid digit found in
/// string (element 2)`). An `NA_character_` element is refused
/// (`NA is not allowed (element 3)`), not parsed as `""`.
///
/// For numbers read like R's `as.numeric()`, with `NA` as `None`, use
/// [`AsNumericVec`] instead.
///
/// # Example
///
/// ```ignore
/// use std::net::IpAddr;
///
/// #[miniextendr]
/// fn parse_ips(addrs: AsFromStrVec<IpAddr>) -> Vec<bool> {
///     addrs.0.into_iter().map(|ip| ip.is_loopback()).collect()
/// }
/// // R: parse_ips(c("127.0.0.1", "8.8.8.8")) → c(TRUE, FALSE)
/// ```
#[derive(Debug, Clone)]
pub struct AsFromStrVec<T>(pub Vec<T>);

impl<T: std::str::FromStr> crate::from_r::TryFromSexp for AsFromStrVec<T>
where
    T::Err: std::fmt::Display,
{
    type Error = crate::from_r::SexpError;
    const CHARACTER_ONLY: bool = true;

    fn try_from_sexp(sexp: crate::SEXP) -> Result<Self, Self::Error> {
        let strings: Vec<Option<&str>> = crate::from_r::TryFromSexp::try_from_sexp(sexp)?;
        let mut result = Vec::with_capacity(strings.len());
        let mut errors = crate::from_r::BatchedErrors::default();
        for (i, s) in strings.into_iter().enumerate() {
            match s {
                None => errors.push(i, || "NA is not allowed".to_string()),
                Some(s) => match s.parse::<T>() {
                    Ok(v) => result.push(v),
                    Err(e) => errors.push(i, || format!("{s:?}: {e}")),
                },
            }
        }
        if errors.is_empty() {
            Ok(AsFromStrVec(result))
        } else {
            Err(errors.into_element_error())
        }
    }
}

/// Each value's `Display` text as a character vector, which the marker parses
/// back element by element (see [`AsFromStr`]'s `IntoR`).
impl<T: std::fmt::Display> IntoR for AsFromStrVec<T> {
    type Error = <Vec<String> as IntoR>::Error;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        display_strings(self.0).try_into_sexp()
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        unsafe { display_strings(self.0).try_into_sexp_unchecked() }
    }

    #[inline]
    fn into_sexp(self) -> crate::SEXP {
        display_strings(self.0).into_sexp()
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe { display_strings(self.0).into_sexp_unchecked() }
    }
}

fn display_strings<T: std::fmt::Display>(values: Vec<T>) -> Vec<String> {
    values.into_iter().map(|v| v.to_string()).collect()
}
// endregion

// region: Collect — zero-allocation iterator-to-R-vector adapters
//
// Naming-convention exemption: the four `Collect*` types below are
// representation-forcing `IntoR` wrappers, like the `As*` family above, but they
// intentionally diverge from the `As*` prefix. `As*` wraps a finished value `T`
// and re-routes its conversion; `Collect*` wraps an *iterator*
// (`I: ExactSizeIterator`) and drains it straight into a freshly allocated R
// vector. The `As*`-of-`T` shape does not describe an iterator adapter, so
// `Collect` (the verb for the operation) is the accurate name. See the module-level
// docs, `analysis/conversion-control-surface-2026-06-07.md` (§3.4 / §4.5), and #871.

/// Write an `ExactSizeIterator` of native R types directly into an R vector.
///
/// Skips the intermediate `Vec` allocation — the R vector is allocated once
/// and the iterator writes directly into it.
///
/// Requires `ExactSizeIterator` because R vectors must know their length
/// at allocation time.
///
/// # Naming
///
/// `Collect` is in the representation-forcing wrapper family but does not take the
/// `As*` prefix used by [`AsList`] / [`AsExternalPtr`] / [`AsRNative`]: those wrap a
/// finished value `T`, whereas `Collect` wraps an *iterator* and materializes it into
/// an R vector. The divergence is intentional — see the module docs and #871.
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn sines(n: i32) -> Collect<impl ExactSizeIterator<Item = f64>> {
///     Collect((0..n).map(|i| (i as f64).sin()))
/// }
/// ```
pub struct Collect<I>(pub I);

impl<I, T> IntoR for Collect<I>
where
    I: ExactSizeIterator<Item = T>,
    T: crate::RNativeType,
{
    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 {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector::<T>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val;
            }
            sexp
        }
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector_unchecked::<T>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val;
            }
            sexp
        }
    }
}

/// Write an `ExactSizeIterator` of `String` directly into an R character vector.
///
/// Strings require per-element CHARSXP allocation (no bulk `copy_from_slice`),
/// so this is a separate type from [`Collect`]. Like [`Collect`], it is an
/// iterator adapter and is exempt from the `As*` naming convention (see #871).
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn upper(words: Vec<String>) -> CollectStrings<impl ExactSizeIterator<Item = String>> {
///     CollectStrings(words.into_iter().map(|w| w.to_uppercase()))
/// }
/// ```
pub struct CollectStrings<I>(pub I);

impl<I> IntoR for CollectStrings<I>
where
    I: ExactSizeIterator<Item = String>,
{
    type Error = std::convert::Infallible;

    #[inline]
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        // Collect String refs for str_iter_to_strsxp.
        let strings: Vec<String> = self.0.collect();
        Ok(crate::into_r::str_iter_to_strsxp(
            strings.iter().map(|s| s.as_str()),
        ))
    }

    #[inline]
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        let strings: Vec<String> = self.0.collect();
        Ok(unsafe {
            crate::into_r::str_iter_to_strsxp_unchecked(strings.iter().map(|s| s.as_str()))
        })
    }
}

/// Write an `ExactSizeIterator` of `Option<T>` directly into an R vector with NA support.
///
/// `None` values become `NA` in R. Works for `f64` and `i32`.
///
/// Like [`Collect`], this is an iterator adapter and is exempt from the `As*`
/// naming convention (see #871).
///
/// # Example
///
/// ```ignore
/// #[miniextendr]
/// fn with_gaps(n: i32) -> CollectNA<impl ExactSizeIterator<Item = Option<f64>>> {
///     CollectNA((0..n).map(|i| if i % 3 == 0 { None } else { Some(i as f64) }))
/// }
/// ```
pub struct CollectNA<I>(pub I);

impl<I> IntoR for CollectNA<I>
where
    I: ExactSizeIterator<Item = 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 {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector::<f64>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val.unwrap_or(crate::altrep_traits::NA_REAL);
            }
            sexp
        }
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector_unchecked::<f64>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val.unwrap_or(crate::altrep_traits::NA_REAL);
            }
            sexp
        }
    }
}

/// Write an `ExactSizeIterator` of `Option<i32>` directly into an R integer vector with NA.
///
/// Like [`Collect`], this is an iterator adapter and is exempt from the `As*`
/// naming convention (see #871).
pub struct CollectNAInt<I>(pub I);

impl<I> IntoR for CollectNAInt<I>
where
    I: ExactSizeIterator<Item = 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 {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector::<i32>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val.unwrap_or(crate::altrep_traits::NA_INTEGER);
            }
            sexp
        }
    }

    #[inline]
    unsafe fn into_sexp_unchecked(self) -> crate::SEXP {
        unsafe {
            let (sexp, dst) = crate::into_r::alloc_r_vector_unchecked::<i32>(self.0.len());
            for (slot, val) in dst.iter_mut().zip(self.0) {
                *slot = val.unwrap_or(crate::altrep_traits::NA_INTEGER);
            }
            sexp
        }
    }
}
// endregion

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

    /// A trait's View converts each argument with `IntoR`, so every reading
    /// marker (and the `Option` of those that read `NULL`) is `IntoR`. The
    /// round trip through a real R is tested in `tests/as_numeric.rs` and
    /// `tests/as_character.rs` (`markers_round_trip`), and through a trait's
    /// View in rpkg (`marker_args_through_view`).
    #[test]
    fn reading_markers_are_into_r() {
        fn into_r<T: IntoR>() {}
        into_r::<AsNumeric>();
        into_r::<AsNumericVec>();
        into_r::<Option<AsNumeric>>();
        into_r::<Option<AsNumericVec>>();
        into_r::<AsCharacter>();
        into_r::<AsCharacterVec>();
        into_r::<Option<AsCharacter>>();
        into_r::<Option<AsCharacterVec>>();
        into_r::<AsFromStr<std::net::IpAddr>>();
        into_r::<AsFromStrVec<std::net::IpAddr>>();
    }
}