Struct ListBuilder 

pub struct ListBuilder<'a> {
    list: SEXP,
    _scope: &'a ProtectScope,
}

Builder for constructing lists with efficient protection management.

ListBuilder holds a reference to a ProtectScope, allowing multiple elements to be inserted without repeatedly protecting/unprotecting each one. This is more efficient than using List::set_elt in a loop.

Example

unsafe fn build_list(n: isize) -> SEXP {
    let scope = ProtectScope::new();
    let builder = ListBuilder::new(&scope, n);

    for i in 0..n {
        // Allocations inside the loop are protected by the scope
        let child = scope.alloc_real(10).into_raw();
        builder.set(i, child);
    }

    builder.into_sexp()
}

Fields

list: SEXP

_scope: &'a ProtectScope

Implementations

impl<'a> ListBuilder<'a>

pub unsafe fn new(scope: &'a ProtectScope, len: usize) -> Self

Create a new list builder with the given length.

The list is allocated and protected using the provided scope.

Safety

Must be called from the R main thread.

pub unsafe fn new_unchecked(scope: &'a ProtectScope, len: usize) -> Self

Create a new list builder via the unchecked FFI allocation path.

_unchecked twin of new: the VECSXP is allocated with Rf_allocVector_unchecked (see ProtectScope::alloc_vecsxp_unchecked), bypassing the main-thread assertion. Use inside ALTREP callbacks, with_r_unwind_protect, or with_r_thread bodies, and pair element insertion with set_unchecked.

Safety

Must be called from the R main thread, in a context where the checked-FFI assertion is intentionally bypassed (see CLAUDE.md “FFI thread checking”).

pub unsafe fn from_protected(scope: &'a ProtectScope, list: SEXP) -> Self

Create a builder wrapping an existing protected list.

Safety

• Must be called from the R main thread
• list must be a valid, protected VECSXP

pub unsafe fn set(&self, idx: isize, child: SEXP)

Set an element at the given index.

The child should be protected by the same scope (or a parent scope). Use scope.protect_raw(...) before calling this method.

Safety

• child must be a valid SEXP
• child should be protected (typically via the same scope)

pub unsafe fn set_unchecked(&self, idx: isize, child: SEXP)

Set an element via the unchecked FFI path.

_unchecked twin of set: inserts with set_vector_elt_unchecked, bypassing the main-thread assertion. Pair with new_unchecked inside ALTREP callbacks, with_r_unwind_protect, or with_r_thread bodies.

Safety

• child must be a valid SEXP, already protected (typically by the same scope, or by being inserted into this protected parent immediately after allocation with no intervening allocation)
• Must be called from the R main thread, in a checked-bypass context

pub unsafe fn set_protected(&self, idx: isize, child: SEXP)

Set an element, protecting the child within the builder’s scope.

This is a convenience method that protects the child and then inserts it.

Safety

• child must be a valid SEXP

pub fn as_sexp(&self) -> SEXP

Get the underlying list SEXP.

pub fn into_list(self) -> List

Convert to a List wrapper.

pub fn into_sexp(self) -> SEXP

Convert to the underlying SEXP.

pub fn len(&self) -> isize

Get the length of the list.

pub fn is_empty(&self) -> bool

Check if the list is empty.

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