Struct Root 

pub struct Root<'a> {
    sexp: SEXP,
    scope: &'a ProtectScope,
}

A rooted SEXP tied to the lifetime of a ProtectScope.

This type has no Drop. The scope owns unprotection responsibility. This makes Root cheap to move and copy (the SEXP and its scope reference).

Lifetime

The 'a lifetime ties the root to its creating scope. The compiler ensures you cannot use the root after the scope has been dropped.

Fields

sexp: SEXP

scope: &'a ProtectScope

Implementations

impl<'a> Root<'a>

pub(crate) unsafe fn protect_child(self, child: SEXP) -> Self

Root child, an element read from this root, for this root’s lifetime.

An ordinary vector holds its elements, so its root already covers them. An ALTREP accessor may return a fresh object that its parent does not keep; the scope then retains it in a lazily allocated pool until the scope drops, without a PROTECT stack entry per element.

Safety

R’s main thread; child must be live on entry.

pub(crate) fn child_roots(self) -> &'a ChildRoots

Retention storage borrowed by views that read their elements lazily.

pub fn get(&self) -> SEXP

Get the underlying SEXP.

pub fn into_raw(self) -> SEXP

Consume the root and return the underlying SEXP.

The SEXP remains protected until the scope drops.

Methods from Deref<Target = SEXP>

pub fn is_null_ptr(self) -> bool

Is this SEXP a C null pointer (address 0x0)?

This answers a pointer question, not an R question. An SEXP that R hands you (a .Call() argument, a list element, an attribute) is never a C null pointer: R’s NULL is the R_NilValue singleton, a real object at a non-zero address. A C null pointer only shows up where C code uses address zero for “nothing here”: an uninitialised static or field (SEXP::null()), an ALTREP data1/data2 slot that was never set, or an FFI function that returns NULL on failure.

To ask “is this R’s NULL?”, use SEXP::is_nil().

use miniextendr_api::SEXP;

let unset = SEXP::null();
assert!(unset.is_null_ptr());

There is no SEXP::is_null(): the name read like a test for R’s NULL, so it is gone on purpose.

use miniextendr_api::SEXP;

let unset = SEXP::null();
assert!(unset.is_null());

See also: SEXP::is_nil(), SEXP::is_null_or_nil(), SEXP::null()

pub fn is_nil(self) -> bool

Is this SEXP R’s NULL (R_NilValue)?

This is the check for an R value: an optional argument that defaults to NULL, an absent attribute, an empty list slot. It compares the address against the R_NilValue singleton and never dereferences self, so it is safe on a stale SEXP. A C null pointer is not R’s NULL; for that, use SEXP::is_null_ptr().

use miniextendr_api::SEXP;

// `x` is an argument whose R default is `NULL`: `f()` and `f(NULL)`
// both arrive as `R_NilValue`.
fn given(x: SEXP) -> bool {
    !x.is_nil()
}

See also: SEXP::nil(), SEXP::is_null_ptr(), SEXP::is_null_or_nil()

pub fn is_null_or_nil(self) -> bool

Is this SEXP either a C null pointer or R’s NULL?

For a slot that can hold either kind of “nothing”: unset (address zero) or set to R_NilValue, such as an external pointer’s protected value. For an R value alone, SEXP::is_nil() is the right check.

use miniextendr_api::SEXP;

// A slot that was never set counts as empty.
assert!(SEXP::null().is_null_or_nil());

See also: SEXP::is_nil(), SEXP::is_null_ptr()

pub fn as_ptr(self) -> *mut SEXPREC

Get the raw pointer.

pub unsafe fn altrep_data1_raw(self) -> SEXP

Get the raw SEXP in the ALTREP data1 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data1_raw_unchecked(self) -> SEXP

Get the raw SEXP in the ALTREP data1 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data1(self, v: SEXP)

Set the ALTREP data1 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data2_raw(self) -> SEXP

Get the raw SEXP in the ALTREP data2 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data2_raw_unchecked(self) -> SEXP

Get the raw SEXP in the ALTREP data2 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data2(self, v: SEXP)

Set the ALTREP data2 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data2_unchecked(self, v: SEXP)

Set the ALTREP data2 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

Trait Implementations

impl<'a> Clone for Root<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for Root<'a>

impl<'a> Deref for Root<'a>

type Target = SEXP

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> TrivialClone for Root<'a>

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: 16 bytes