Trait IntoRAltrep

Source

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 { ... }
}

Expand description

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, ffi::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()
}