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.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes