Skip to main content

Lazy

miniextendr_api::into_r::altrep

Type Alias Lazy 

Source 
pub type Lazy<T> = Altrep<T>;
Expand description

Marker type to opt-in to ALTREP representation for types that have both eager-copy and ALTREP implementations.

§Motivation

Types like Vec<i32> have two possible conversions to R:

  1. Eager copy (default): copies all data to R immediately
  2. ALTREP: keeps data in Rust, provides it on-demand to R

The default IntoR for Vec<i32> does eager copy. To get ALTREP behavior, wrap your value in Altrep<T>.

§Example

ⓘ
use miniextendr_api::{miniextendr, Altrep};

// Returns an ALTREP-backed integer vector (data stays in Rust)
#[miniextendr]
fn altrep_vec() -> Altrep<Vec<i32>> {
    Altrep((0..1_000_000).collect())
}

// Returns a regular R vector (data copied to R)
#[miniextendr]
fn regular_vec() -> Vec<i32> {
    (0..1_000_000).collect()
}

§Supported Types

Altrep<T> works with any type that implements both:

Built-in supported types:

  • Vec<i32>, Vec<f64>, Vec<bool>, Vec<u8>, Vec<String>
  • Box<[i32]>, Box<[f64]>, Box<[bool]>, Box<[u8]>, Box<[String]>
  • Range<i32>, Range<i64>, Range<f64>

Opt-in lazy materialization via ALTREP.

Wrapping a return type in Lazy<T> causes it to be returned as an ALTREP vector backed by Rust-owned memory. R reads elements on demand; full materialization only happens if R needs a contiguous pointer.

§When to use

  • Large vectors (>1000 elements)
  • Data R may only partially read
  • Computed/external data (Arrow, ndarray, nalgebra)

§When NOT to use

  • Small vectors (<100 elements, ALTREP overhead dominates)
  • Data R will immediately modify (triggers instant materialization)

§Example

ⓘ
#[miniextendr]
fn big_result() -> Lazy<Vec<f64>> {
    Lazy(vec![0.0; 1_000_000])
}

Aliased Type§

#[repr(transparent)]
pub struct Lazy<T>(pub T);

Tuple Fields§

§0: T