Struct List

Source

pub struct List(SEXP);

Expand description

Owned handle to an R list (VECSXP).

§Examples

use miniextendr_api::list::List;

let list = List::from_values(vec![1i32, 2, 3]);
assert_eq!(list.len(), 3);
let first: Option<i32> = list.get_index(0);

Tuple Fields§

§0: SEXP

Implementations§

Source §

impl List

Source

pub fn as_data_frame(&self) -> Result<DataFrameView, DataFrameError>

Promote this named list to a DataFrameView.

The list must have a names attribute and all columns must have equal length.

§Errors

Returns DataFrameError if the list has no names or columns differ in length.

Source §

impl List

Source

pub fn is_list(self) -> bool

Return true if the underlying SEXP is a list (VECSXP) according to R.

Source

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

Wrap an existing VECSXP without additional checks.

§Safety

Caller must ensure sexp is a valid list object (typically a VECSXP or a pairlist coerced to VECSXP) whose lifetime remains managed by R.

Source

pub const fn as_sexp(self) -> SEXP

Get the underlying SEXP.

Source

pub fn len(self) -> isize

Length of the list (number of elements).

Source

pub fn is_empty(self) -> bool

Returns true if the list is empty.

Source

pub fn get(self, idx: isize) -> Option<SEXP>

Get raw SEXP element at 0-based index. Returns None if out of bounds.

Source

pub fn get_index<T>(self, idx: isize) -> Option<T>
where T: TryFromSexp<Error = SexpError>,

Get element at 0-based index and convert to type T.

Returns None if index is out of bounds or conversion fails.

Source

pub fn get_named<T>(self, name: &str) -> Option<T>
where T: TryFromSexp<Error = SexpError>,

Get element by name and convert to type T.

Returns None if name not found or conversion fails.

Source

fn get_attr_opt(self, name: SEXP) -> Option<SEXP>

Get an arbitrary attribute by symbol, returning None for R_NilValue.

Source

pub fn names(self) -> Option<SEXP>

Get the names attribute if present.

Source

pub fn get_class(self) -> Option<SEXP>

Get the class attribute if present.

Source

pub fn get_dim(self) -> Option<SEXP>

Get the dim attribute if present.

Source

pub fn get_dimnames(self) -> Option<SEXP>

Get the dimnames attribute if present.

Source

pub fn get_rownames(self) -> Option<SEXP>

Get row names from the dimnames attribute.

Source

pub fn get_colnames(self) -> Option<SEXP>

Get column names from the dimnames attribute.

Source

pub fn get_levels(self) -> Option<SEXP>

Get the levels attribute if present (for factors).

Source

pub fn get_tsp(self) -> Option<SEXP>

Get the tsp attribute if present (for time series).

Source

pub fn set_names(self, names: SEXP) -> Self

Set the names attribute; returns the same list for chaining.

Equivalent to R’s SET_NAMES(x, n).

Source

pub fn set_class(self, class: SEXP) -> Self

Set the class attribute; returns the same list for chaining.

Equivalent to R’s SET_CLASS(x, n).

Source

pub fn set_dim(self, dim: SEXP) -> Self

Set the dim attribute; returns the same list for chaining.

Equivalent to R’s SET_DIM(x, n).

Source

pub fn set_dimnames(self, dimnames: SEXP) -> Self

Set the dimnames attribute; returns the same list for chaining.

Equivalent to R’s SET_DIMNAMES(x, n).

Source

pub fn set_levels(self, levels: SEXP) -> Self

Set the levels attribute; returns the same list for chaining.

Equivalent to R’s SET_LEVELS(x, l).

Source

pub fn set_class_str(self, classes: &[&str]) -> Self

Set the class attribute from a slice of class names.

This is a convenience wrapper that creates a character vector from the provided strings and sets it as the class attribute.

§Example

let list = List::from_pairs(vec![("x", vec![1, 2, 3])]);
let df = list.set_class_str(&["data.frame"]);

Source

pub fn set_data_frame_class(self) -> Self

Set class = "data.frame" using a cached class STRSXP.

Equivalent to set_class_str(&["data.frame"]) but avoids allocation.

Source

pub fn set_names_str(self, names: &[&str]) -> Self

Set the names attribute from a slice of strings.

This is a convenience wrapper that creates a character vector from the provided strings and sets it as the names attribute.

§Example

let list = List::from_values(vec![1, 2, 3]);
let named = list.set_names_str(&["a", "b", "c"]);

Source

pub fn set_row_names_int(self, n: usize) -> Self

Set row.names for a data.frame using compact integer form.

R internally represents row.names as a compact integer vector c(NA_integer_, -n) when the row names are just 1:n. This is more memory-efficient than storing n strings.

§Example

let list = List::from_pairs(vec![
    ("x", vec![1, 2, 3]),
    ("y", vec![4, 5, 6]),
])
.set_class_str(&["data.frame"])
.set_row_names_int(3);  // Row names: "1", "2", "3"

Source

pub fn set_row_names_str(self, row_names: &[&str]) -> Self

Set row.names from a vector of strings.

Use this when you need custom row names. For simple sequential row names (1, 2, 3, …), use set_row_names_int instead.

§Example

let list = List::from_pairs(vec![
    ("x", vec![1, 2, 3]),
])
.set_class_str(&["data.frame"])
.set_row_names_str(&["row_a", "row_b", "row_c"]);

Source

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

Set an element at the given index, protecting the child during insertion.

This is the safe way to insert a freshly allocated SEXP into a list. The child is protected for the duration of the SET_VECTOR_ELT call, ensuring it cannot be garbage collected.

§Safety

Must be called from the R main thread
child must be a valid SEXP
self must be a valid, protected VECSXP

§Panics

Panics if idx is out of bounds.

§Example

let scope = ProtectScope::new();
let list = List::from_raw(scope.alloc_vecsxp(n).into_raw());

for i in 0..n {
    let child = Rf_allocVector(REALSXP, 10);  // unprotected!
    list.set_elt(i, child);  // safe: protects child during insertion
}

Source

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

Set an element without protecting the child.

§Safety

In addition to the safety requirements of set_elt:

The caller must ensure child is already protected or that no GC can occur between child allocation and this call.

Use this for performance when you know the child is already protected (e.g., it’s a child of another protected container, or you have an OwnedProtect guard for it).

Source

pub unsafe fn set_elt_with<F>(self, idx: isize, f: F)
where F: FnOnce() -> SEXP,

Set an element using a callback that produces the child.

The callback is executed within a protection scope, so any allocations it performs are protected until insertion completes.

§Safety

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

§Example

let list = List::from_raw(scope.alloc_vecsxp(n).into_raw());

for i in 0..n {
    list.set_elt_with(i, || {
        let vec = Rf_allocVector(REALSXP, 10);
        fill_vector(vec);  // can allocate internally
        vec
    });
}

Source §

impl List

Source

pub fn from_pairs<N, T>(pairs: Vec<(N, T)>) -> Self
where N: AsRef<str>, T: IntoR,

Build a list from (name, value) pairs, setting names in one pass.

Source

pub fn from_values<T: IntoR>(values: Vec<T>) -> Self

Build an unnamed list from values.

Use this for tuple-like structures where positional access is more natural.

§Example

let list = List::from_values(vec![1i32, 2i32, 3i32]);
// R: list(1L, 2L, 3L) - accessed as [[1]], [[2]], [[3]]

Source

pub fn from_raw_values(values: Vec<SEXP>) -> Self

Build an unnamed list from pre-converted SEXPs.

§Safety Note

The input SEXPs should already be protected or be children of protected containers. This function protects the list during construction.

Source

pub fn from_scalars_or_list(elements: &[SEXP]) -> Self

Build an atomic vector from homogeneous length-1 scalar SEXPs.

If all elements are length-1 scalars of the same coalesceable type (INTSXP, REALSXP, LGLSXP, STRSXP), returns that atomic vector. Otherwise returns a VECSXP (generic list).

This is the canonical entry point for both DataFrame::into_data_frame (column building) and SeqSerializer::end (sequence coalescing).

§Safety Note

The input SEXPs should already be protected or be children of protected containers.

Source

pub fn from_raw_pairs<N>(pairs: Vec<(N, SEXP)>) -> Self
where N: AsRef<str>,

Build a list from (name, SEXP) pairs (heterogeneous-friendly).

§Safety Note

The input SEXPs should already be protected or be children of protected containers. This function protects the list and names vector during construction.