Struct AltrepSexp 

pub struct AltrepSexp {
    sexp: SEXP,
    _not_send: PhantomData<Rc<()>>,
}

A SEXP known to be ALTREP. !Send + !Sync — must be materialized on the R main thread before data can be accessed or sent to other threads.

This type prevents ALTREP vectors from being accidentally sent to rayon or other worker threads where DATAPTR_RO would invoke R internals (undefined behavior).

As a #[miniextendr] parameter

AltrepSexp implements TryFromSexp, so it can be used directly as a function parameter. It only accepts ALTREP vectors — non-ALTREP input produces an error.

#[miniextendr]
pub fn altrep_info(x: AltrepSexp) -> String {
    format!("{:?}, len={}", x.sexptype(), x.len())
}

altrep_info(1:10)          # OK — 1:10 is ALTREP
altrep_info(c(1L, 2L, 3L)) # Error: "expected an ALTREP vector"

Construction

• AltrepSexp::try_wrap — runtime check, returns None if not ALTREP
• AltrepSexp::from_raw — unsafe, caller asserts ALTREP(sexp) != 0

Materialization

All materialization methods must be called on the R main thread.

• AltrepSexp::materialize — forces R to materialize, returns plain SEXP
• AltrepSexp::materialize_integer — materialize INTSXP and return &[i32]
• AltrepSexp::materialize_real — materialize REALSXP and return &[f64]
• AltrepSexp::materialize_logical — materialize LGLSXP and return &[i32]
• AltrepSexp::materialize_raw — materialize RAWSXP and return &[u8]
• AltrepSexp::materialize_complex — materialize CPLXSXP and return &[Rcomplex]
• AltrepSexp::materialize_strings — materialize STRSXP to Vec<Option<String>>

Thread safety

AltrepSexp is !Send + !Sync (via PhantomData<Rc<()>>). This is a compile-time guarantee: you cannot send an un-materialized ALTREP vector to another thread. Call one of the materialize_* methods first to get a Send + Sync slice or SEXP.

Fields

sexp: SEXP

_not_send: PhantomData<Rc<()>>

PhantomData<Rc<()>> makes this type !Send + !Sync.

Implementations

impl AltrepSexp

pub unsafe fn from_raw(sexp: SEXP) -> Self

Wrap a SEXP that is known to be ALTREP.

Safety

Caller must ensure ALTREP(sexp) is true (non-zero).

pub fn try_wrap(sexp: SEXP) -> Option<Self>

Check a SEXP and wrap if ALTREP. Returns None if not ALTREP.

pub unsafe fn materialize(self) -> SEXP

Force materialization and return the (now materialized) SEXP.

For contiguous types (INTSXP, REALSXP, LGLSXP, RAWSXP, CPLXSXP), calls DATAPTR_RO to trigger ALTREP materialization. For STRSXP, iterates STRING_ELT to force element materialization.

After this call, the SEXP’s data pointer is stable and can be safely accessed from any thread (the SEXP itself is still Send + Sync).

Safety

Must be called on the R main thread.

pub unsafe fn materialize_real(&self) -> &[f64]

Materialize and return a typed slice of f64 (REALSXP).

Safety

Must be called on the R main thread. The SEXP must be REALSXP.

pub unsafe fn materialize_integer(&self) -> &[i32]

Materialize and return a typed slice of i32 (INTSXP).

Safety

Must be called on the R main thread. The SEXP must be INTSXP.

pub unsafe fn materialize_logical(&self) -> &[i32]

Materialize and return a typed slice of i32 (LGLSXP, R’s internal logical storage).

Safety

Must be called on the R main thread. The SEXP must be LGLSXP.

pub unsafe fn materialize_raw(&self) -> &[u8]

Materialize and return a typed slice of u8 (RAWSXP).

Safety

Must be called on the R main thread. The SEXP must be RAWSXP.

pub unsafe fn materialize_complex(&self) -> &[Rcomplex]

Materialize and return a typed slice of Rcomplex (CPLXSXP).

Safety

Must be called on the R main thread. The SEXP must be CPLXSXP.

pub unsafe fn materialize_strings(&self) -> Vec<Option<String>>

Materialize strings into owned Rust data.

Each element is None for NA_character_, or Some(String) otherwise.

Safety

Must be called on the R main thread. The SEXP must be STRSXP.

pub unsafe fn as_raw(&self) -> SEXP

Get the inner SEXP without materializing.

Safety

The returned SEXP is still ALTREP. Do not call DATAPTR_RO on it from a non-R thread.

pub fn sexptype(&self) -> SEXPTYPE

Get the SEXPTYPE of the underlying vector.

pub fn len(&self) -> usize

Get the length of the underlying vector.

pub fn is_empty(&self) -> bool

Check if the underlying vector is empty.

Trait Implementations

impl Debug for AltrepSexp

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoR for AltrepSexp

Convert AltrepSexp to R by returning the inner SEXP.

This allows AltrepSexp to be used as a return type from #[miniextendr] functions, transparently passing the ALTREP SEXP back to R.

type Error = Infallible

The error type for fallible conversions.

fn try_into_sexp(self) -> Result<SEXP, Self::Error>

Try to convert this value to an R SEXP.

unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error>

Try to convert to SEXP without thread safety checks.

fn into_sexp(self) -> SEXP

Convert this value to an R SEXP, panicking on error.

unsafe fn into_sexp_unchecked(self) -> SEXP

where Self: Sized,

Convert to SEXP without thread safety checks, panicking on error.

impl TryFromSexp for AltrepSexp

Conversion from R SEXP to AltrepSexp.

Only succeeds if the input is an ALTREP vector (ALTREP(sexp) != 0). Non-ALTREP input produces SexpError::InvalidValue.

This is the inverse of TryFromSexp for SEXP, which accepts any SEXP but auto-materializes ALTREP.

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.