Trait IntoRAltrep 

pub trait IntoRAltrep {
    // Required method
    fn into_sexp_altrep(self) -> SEXP;

    // Provided methods
    unsafe fn into_sexp_altrep_unchecked(self) -> SEXP
       where Self: Sized { ... }
    fn into_altrep(self) -> Altrep<Self>
       where Self: Sized { ... }
}

Extension trait for ALTREP conversions.

This trait provides ergonomic methods for converting Rust types to R ALTREP vectors without copying data. The data stays in Rust memory (wrapped in an ExternalPtr) and R accesses it via ALTREP callbacks.

Performance Characteristics

Operation	Regular (IntoR)	ALTREP (IntoRAltrep)
Creation	O(n) copy	O(1) wrap
Memory	Duplicated in R	Single copy in Rust
Element access	Direct pointer	Callback (~10ns overhead)
DATAPTR ops	O(1)	O(1) if Vec/Box, N/A if lazy

When to Use ALTREP

Good candidates:

• ✅ Large vectors (>1000 elements)
• ✅ Lazy/computed data (avoid eager materialization)
• ✅ External data sources (files, databases, APIs)
• ✅ Data that might not be fully accessed by R

Not recommended:

• ❌ Small vectors (<100 elements) - copy overhead is negligible
• ❌ Data R will immediately modify (triggers copy anyway)
• ❌ Temporary results (extra indirection not worth it)

Example

use miniextendr_api::{miniextendr, IntoRAltrep, IntoR, SEXP};

#[miniextendr]
fn large_dataset() -> SEXP {
    let data: Vec<f64> = (0..1_000_000).map(|i| i as f64).collect();

    // Zero-copy: wraps pointer instead of copying 1M elements
    data.into_sexp_altrep()
}

#[miniextendr]
fn small_result() -> SEXP {
    let data = vec![1, 2, 3, 4, 5];

    // Regular copy is fine for small data
    data.into_sexp()
}

Required Methods

fn into_sexp_altrep(self) -> SEXP

Convert to R SEXP using ALTREP zero-copy representation.

This is equivalent to Altrep(self).into_sexp() but more discoverable and explicit about the zero-copy intent.

Provided Methods

unsafe fn into_sexp_altrep_unchecked(self) -> SEXP

where Self: Sized,

Convert to R SEXP using ALTREP, skipping debug thread assertions.

Safety

Caller must ensure they are on R’s main thread.

fn into_altrep(self) -> Altrep<Self>

where Self: Sized,

Create an Altrep<Self> wrapper.

This returns the wrapper explicitly, allowing you to store it or further process it before conversion.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<T> IntoRAltrep for T

where T: RegisterAltrep + TypedExternal,