1#![allow(rustdoc::private_intra_doc_links)]
2//! Thin wrapper around R list (`VECSXP`).
3//!
4//! Provides safe construction from Rust values and typed extraction.
5//!
6//! # Submodules
7//!
8//! | Module | Contents |
9//! |--------|----------|
10//! | [`accumulator`] | `ListAccumulator` — dynamic list construction with bounded protect stack |
11//! | [`named`] | `NamedList` — O(1) name-indexed access via `HashMap` index |
12//!
13//! # Core Types
14//!
15//! - [`List`] — owned handle to an R list (VECSXP)
16//! - [`ListMut`] — mutable view for in-place element replacement
17//! - [`ListBuilder`] — fixed-size batch construction
18//! - [`NamedListBuilder`] — owned, GC-rooted named lists and data frames
19//! - [`BuiltList`] — the builder's rooted plain-list finish
20//! - [`IntoList`] / [`TryFromList`] — conversion traits
2122mod named_builder;
23pub use named_builder::{BuiltList, NamedListBuilder};
2425use crate::SEXPTYPE::{NILSXP, STRSXP, VECSXP};
26use crate::from_r::{
27ElementCheck, SexpError, SexpLengthError, SexpTypeError, TryFromSexp, map_vecsxp_batched,
28no_element_check, try_charsxp_to_str,
29};
30use crate::gc_protect::OwnedProtect;
31use crate::into_r::IntoR;
32use crate::sys::{self};
33use crate::{SEXP, SexpExt};
34use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
35use std::hash::Hash;
3637/// Owned handle to an R list (`VECSXP`).
38///
39/// # Examples
40///
41/// ```no_run
42/// use miniextendr_api::list::List;
43///
44/// let list = List::from_values(vec![1i32, 2, 3]);
45/// assert_eq!(list.len(), 3);
46/// let first: Option<i32> = list.get_index(0);
47/// ```
48#[derive(#[automatically_derived]#[doc(hidden)]unsafe impl ::core::clone::TrivialClone
for List {
}
#[automatically_derived]impl ::core::clone::Clone for List {
#[inline]
fn clone(&self) -> Self {
let _: ::core::clone::AssertParamIsClone<SEXP>;
*self
}
}Clone, #[automatically_derived]impl ::core::marker::Copy for List { }Copy, #[automatically_derived]impl ::core::fmt::Debug for List {
#[inline]
fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
::core::fmt::Formatter::debug_struct_field1_finish(f, "List",
&&self.0)
}
}Debug)]
49pub struct List(SEXP);
5051/// Mutable view of an R list (`VECSXP`).
52///
53/// This is a wrapper type instead of `&mut [SEXP]` to avoid exposing a raw slice
54/// that could become invalid if list elements are replaced with `NULL`.
55#[derive(#[automatically_derived]impl ::core::fmt::Debug for ListMut {
#[inline]
fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
::core::fmt::Formatter::debug_struct_field1_finish(f, "ListMut",
&&self.0)
}
}Debug)]
56pub struct ListMut(SEXP);
5758/// The text of the name `charsxp`, read with its own encoding (a Latin-1 name
59/// is translated); `None` for `NA` and for a name that is not text (marked as
60/// bytes, or not valid UTF-8), which nothing can look up by a Rust `&str`.
61pub(crate) fn text_name(charsxp: SEXP) -> Option<&'static str> {
62if charsxp == SEXP::na_string() {
63return None;
64 }
65// SAFETY: a non-NA CHARSXP of a names attribute the caller roots.
66unsafe { try_charsxp_to_str(charsxp) }.ok()
67}
6869impl List {
70/// Return true if the underlying SEXP is a list (VECSXP) according to R.
71 ///
72 /// Uses `SexpExt::is_list` (VECSXP check) — **not** `is_pair_list` (LISTSXP).
73#[inline]
74pub fn is_list(self) -> bool {
75 <SEXPas crate::SexpExt>::is_list(&self.0)
76 }
7778/// Wrap an existing `VECSXP` without additional checks.
79 ///
80 /// # Safety
81 ///
82 /// Caller must ensure `sexp` is a valid list (`VECSXP`) that stays rooted
83 /// while the `List` is used: `List` is a `Copy` view and roots nothing.
84#[inline]
85pub const unsafe fn from_raw(sexp: SEXP) -> Self {
86List(sexp)
87 }
8889/// Get the underlying `SEXP`.
90#[inline]
91pub const fn as_sexp(self) -> SEXP {
92self.0
93}
9495/// Length of the list (number of elements).
96#[inline]
97pub fn len(self) -> isize {
98self.0.xlength()
99 }
100101/// Returns true if the list is empty.
102#[inline]
103pub fn is_empty(self) -> bool {
104self.len() == 0
105}
106107/// Get raw SEXP element at 0-based index. Returns `None` if out of bounds.
108#[inline]
109pub fn get(self, idx: isize) -> Option<SEXP> {
110if idx < 0 || idx >= self.len() {
111return None;
112 }
113Some(self.0.vector_elt(idx))
114 }
115116/// Get element at 0-based index and convert to type `T`.
117 ///
118 /// Returns `None` if index is out of bounds or conversion fails.
119 ///
120 /// The conversion error is discarded, so `T`'s `TryFromSexp::Error` is
121 /// unconstrained — any element type works, not only those whose error is
122 /// `SexpError`. Callers that need the error (e.g. to distinguish "missing"
123 /// from "wrong type") should use [`get`](Self::get) and convert directly.
124#[inline]
125pub fn get_index<T>(self, idx: isize) -> Option<T>
126where
127T: TryFromSexp,
128 {
129let sexp = self.get(idx)?;
130 T::try_from_sexp(sexp).ok()
131 }
132133/// The names this list can be looked up by: `(position, name)` for each
134 /// element whose name is text ([`text_name`]), in list order. Empty names
135 /// are included. Yields nothing when the list has no `names` attribute.
136 ///
137 /// [`get_named_sexp`](Self::get_named_sexp),
138 /// [`first_duplicate_name`](Self::first_duplicate_name), [`NamedList`] and
139 /// the `#[derive(TryFromList)]` field lookup all walk the names through
140 /// this, so they agree on which names count.
141 ///
142 /// A UTF-8 or native name points into R's CHARSXP cache and stays valid
143 /// while the list (which roots its `names` attribute) is reachable; a
144 /// Latin-1 name is translated into R's memory stack, valid until the
145 /// enclosing `.Call` returns.
146pub(crate) fn text_names(self) -> impl Iterator<Item = (isize, &'static str)> {
147let names = self.names();
148let n = if names.is_some() { self.len() } else { 0 };
149 (0..n).filter_map(move |i| text_name(names?.string_elt(i)).map(|s| (i, s)))
150 }
151152/// Get the raw element `SEXP` associated with `name`, without conversion.
153 ///
154 /// Returns the element exactly as stored so callers can convert it with any
155 /// [`TryFromSexp`] error type — not only those whose error is `SexpError`.
156 /// Returns `None` when the list has no `names` attribute or no name matches.
157 ///
158 /// When the name appears more than once, the first element with that name
159 /// is returned, as R's `x[["name"]]` does.
160pub fn get_named_sexp(self, name: &str) -> Option<SEXP> {
161self.text_names()
162 .find(|&(_, s)| s == name)
163 .map(|(i, _)| self.0.vector_elt(i))
164 }
165166/// The first name that appears more than once in the list, if any.
167 ///
168 /// An R list may repeat a name (`list(a = 1, a = 2)`), and a `List`
169 /// argument accepts such a list, as R does. A function that needs each
170 /// name to be unique checks for it itself, and words its own error:
171 ///
172 /// ```no_run
173 /// use miniextendr_api::{List, miniextendr};
174 ///
175 /// #[miniextendr]
176 /// pub fn settings_count(settings: List) -> i32 {
177 /// if let Some(name) = settings.first_duplicate_name() {
178 /// panic!("`settings` has the name {name:?} more than once; each entry needs a unique name");
179 /// }
180 /// settings.len() as i32
181 /// }
182 /// ```
183 ///
184 /// Only names that can identify an element are compared: `NA` and empty
185 /// names are skipped (R lets any number of elements go unnamed), and so
186 /// are names that are not valid UTF-8. Returns `None` for a list without
187 /// a `names` attribute.
188pub fn first_duplicate_name(self) -> Option<String> {
189let mut seen = HashSet::new();
190self.text_names()
191 .map(|(_, s)| s)
192 .filter(|s| !s.is_empty())
193 .find(|s| !seen.insert(*s))
194 .map(str::to_owned)
195 }
196197/// Positions of a derived struct's fields, for the code
198 /// `#[derive(TryFromList)]` generates. Not public API.
199 ///
200 /// `sorted_fields` holds the struct's field names in ascending byte
201 /// order (the derive sorts them); entry `k` of the result is the position
202 /// of the first element named `sorted_fields[k]`, or `None` when no
203 /// element has that name. One pass over the names, `O(n log fields)`.
204 ///
205 /// A field name that appears more than once is an error
206 /// ([`SexpError::DuplicateName`]): the struct could only keep one of the
207 /// values. Other repeated names are ignored, as names that are not fields
208 /// are.
209#[doc(hidden)]
210pub fn __mx_field_positions<const N: usize>(
211self,
212 sorted_fields: [&str; N],
213 ) -> Result<[Option<isize>; N], SexpError> {
214if true {
if !sorted_fields.is_sorted() {
{
::core::panicking::panic_fmt(format_args!("field names must be sorted"));
}
};
};debug_assert!(sorted_fields.is_sorted(), "field names must be sorted");
215let mut positions = [None; N];
216for (i, name) in self.text_names() {
217if let Ok(k) = sorted_fields.binary_search(&name) {
218if positions[k].is_some() {
219return Err(SexpError::DuplicateName(name.to_owned()));
220 }
221 positions[k] = Some(i);
222 }
223 }
224Ok(positions)
225 }
226227/// Get element by name and convert to type `T`.
228 ///
229 /// Returns `None` if name not found or conversion fails.
230 ///
231 /// The conversion error is discarded, so `T`'s `TryFromSexp::Error` is
232 /// unconstrained. Use [`get_named_sexp`](Self::get_named_sexp) and convert
233 /// directly when you need to inspect the conversion failure.
234pub fn get_named<T>(self, name: &str) -> Option<T>
235where
236T: TryFromSexp,
237 {
238let sexp = self.get_named_sexp(name)?;
239 T::try_from_sexp(sexp).ok()
240 }
241242// region: Attribute getters (equivalent to R's GET_* macros)
243244/// Get an arbitrary attribute by symbol, returning `None` for `R_NilValue`.
245#[inline]
246fn get_attr_opt(self, name: SEXP) -> Option<SEXP> {
247let attr = self.0.get_attr(name);
248if attr.is_nil() { None } else { Some(attr) }
249 }
250251/// Get the `names` attribute if present.
252#[inline]
253pub fn names(self) -> Option<SEXP> {
254self.get_attr_opt(SEXP::names_symbol())
255 }
256257/// Get the `class` attribute if present.
258#[inline]
259pub fn get_class(self) -> Option<SEXP> {
260self.get_attr_opt(SEXP::class_symbol())
261 }
262263/// Get the `dim` attribute if present.
264#[inline]
265pub fn get_dim(self) -> Option<SEXP> {
266self.get_attr_opt(SEXP::dim_symbol())
267 }
268269/// Get the `dimnames` attribute if present.
270#[inline]
271pub fn get_dimnames(self) -> Option<SEXP> {
272self.get_attr_opt(SEXP::dimnames_symbol())
273 }
274275/// Get row names from the `dimnames` attribute.
276#[inline]
277pub fn get_rownames(self) -> Option<SEXP> {
278let dimnames = self.0.get_dimnames();
279if dimnames.is_nil() {
280return None;
281 }
282let rownames = unsafe { sys::Rf_GetRowNames(dimnames) };
283if rownames.is_nil() {
284None285 } else {
286Some(rownames)
287 }
288 }
289290/// Get column names from the `dimnames` attribute.
291#[inline]
292pub fn get_colnames(self) -> Option<SEXP> {
293let dimnames = self.0.get_dimnames();
294if dimnames.is_nil() {
295return None;
296 }
297let colnames = unsafe { sys::Rf_GetColNames(dimnames) };
298if colnames.is_nil() {
299None300 } else {
301Some(colnames)
302 }
303 }
304305/// Get the `levels` attribute if present (for factors).
306#[inline]
307pub fn get_levels(self) -> Option<SEXP> {
308self.get_attr_opt(SEXP::levels_symbol())
309 }
310311/// Get the `tsp` attribute if present (for time series).
312#[inline]
313pub fn get_tsp(self) -> Option<SEXP> {
314self.get_attr_opt(SEXP::tsp_symbol())
315 }
316// endregion
317318 // region: Attribute setters (equivalent to R's SET_* macros)
319320/// Set the `names` attribute; returns the same list for chaining.
321 ///
322 /// Equivalent to R's `SET_NAMES(x, n)`.
323#[inline]
324pub fn set_names(self, names: SEXP) -> Self {
325self.0.set_names(names);
326self327 }
328329/// Set the `class` attribute; returns the same list for chaining.
330 ///
331 /// Equivalent to R's `SET_CLASS(x, n)`.
332#[inline]
333pub fn set_class(self, class: SEXP) -> Self {
334self.0.set_class(class);
335self336 }
337338/// Set the `dim` attribute; returns the same list for chaining.
339 ///
340 /// Equivalent to R's `SET_DIM(x, n)`.
341#[inline]
342pub fn set_dim(self, dim: SEXP) -> Self {
343self.0.set_dim(dim);
344self345 }
346347/// Set the `dimnames` attribute; returns the same list for chaining.
348 ///
349 /// Equivalent to R's `SET_DIMNAMES(x, n)`.
350#[inline]
351pub fn set_dimnames(self, dimnames: SEXP) -> Self {
352self.0.set_dimnames(dimnames);
353self354 }
355356/// Set the `levels` attribute; returns the same list for chaining.
357 ///
358 /// Equivalent to R's `SET_LEVELS(x, l)`.
359#[inline]
360pub fn set_levels(self, levels: SEXP) -> Self {
361self.0.set_levels(levels);
362self363 }
364// endregion
365366 // region: Convenience setters (string-based)
367368/// Set the `class` attribute from a slice of class names.
369 ///
370 /// This is a convenience wrapper that creates a character vector from the
371 /// provided strings and sets it as the class attribute.
372 ///
373 /// # Example
374 ///
375 /// ```ignore
376 /// let list = List::from_pairs(vec![("x", vec![1, 2, 3])]);
377 /// let df = list.set_class_str(&["data.frame"]);
378 /// ```
379#[inline]
380pub fn set_class_str(self, classes: &[&str]) -> Self {
381use crate::SEXPTYPE::STRSXP;
382383let n: isize = classes384 .len()
385 .try_into()
386 .expect("classes length exceeds isize::MAX");
387unsafe {
388// Protect self across the class-vector allocation; otherwise the
389 // parent list can be freed during `Rf_allocVector` while it sits
390 // unrooted in our Rust handle (UAF under gctorture).
391let _self_guard = OwnedProtect::new(self.0);
392let class_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
393for (i, class) in classes.iter().enumerate() {
394let idx: isize = i.try_into().expect("index exceeds isize::MAX");
395 class_vec.get().set_string_elt(idx, SEXP::charsxp(class));
396 }
397self.0.set_class(class_vec.get());
398 }
399self400 }
401402/// Set class = `"data.frame"` using a cached class STRSXP.
403 ///
404 /// Equivalent to `set_class_str(&["data.frame"])` but avoids allocation.
405#[inline]
406pub fn set_data_frame_class(self) -> Self {
407self.0
408.set_class(crate::cached_class::data_frame_class_sexp());
409self410 }
411412/// Set the `names` attribute from a slice of strings.
413 ///
414 /// This is a convenience wrapper that creates a character vector from the
415 /// provided strings and sets it as the names attribute.
416 ///
417 /// # Example
418 ///
419 /// ```ignore
420 /// let list = List::from_values(vec![1, 2, 3]);
421 /// let named = list.set_names_str(&["a", "b", "c"]);
422 /// ```
423#[inline]
424pub fn set_names_str(self, names: &[&str]) -> Self {
425use crate::SEXPTYPE::STRSXP;
426427let n: isize = names428 .len()
429 .try_into()
430 .expect("names length exceeds isize::MAX");
431unsafe {
432// Protect self across the names-vector allocation; see set_class_str.
433let _self_guard = OwnedProtect::new(self.0);
434let names_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
435for (i, name) in names.iter().enumerate() {
436let idx: isize = i.try_into().expect("index exceeds isize::MAX");
437 names_vec.get().set_string_elt(idx, SEXP::charsxp(name));
438 }
439self.0.set_names(names_vec.get());
440 }
441self442 }
443444/// Set `row.names` for a data.frame using compact integer form.
445 ///
446 /// R internally represents row.names as a compact integer vector
447 /// `c(NA_integer_, -n)` when the row names are just `1:n`. This is more
448 /// memory-efficient than storing n strings.
449 ///
450 /// # Example
451 ///
452 /// ```ignore
453 /// let list = List::from_pairs(vec![
454 /// ("x", vec![1, 2, 3]),
455 /// ("y", vec![4, 5, 6]),
456 /// ])
457 /// .set_class_str(&["data.frame"])
458 /// .set_row_names_int(3); // Row names: "1", "2", "3"
459 /// ```
460#[inline]
461pub fn set_row_names_int(self, n: usize) -> Self {
462unsafe {
463// Protect self across the row.names allocation; see set_class_str.
464let _self_guard = OwnedProtect::new(self.0);
465// R's compact row.names: c(NA_integer_, -n)
466let (row_names, rn) = crate::into_r::alloc_r_vector::<i32>(2);
467let _guard = OwnedProtect::new(row_names);
468rn[0] = i32::MIN; // NA_INTEGER
469let n_i32 = i32::try_from(n).unwrap_or_else(|_| {
470{
::core::panicking::panic_fmt(format_args!("row count {0} exceeds i32::MAX",
n));
};panic!("row count {n} exceeds i32::MAX");
471 });
472rn[1] = -n_i32;
473self.0.set_row_names(row_names);
474 }
475self476 }
477478/// Set `row.names` from a vector of strings.
479 ///
480 /// Use this when you need custom row names. For simple sequential row names
481 /// (1, 2, 3, ...), use [`set_row_names_int`](Self::set_row_names_int) instead.
482 ///
483 /// # Example
484 ///
485 /// ```ignore
486 /// let list = List::from_pairs(vec![
487 /// ("x", vec![1, 2, 3]),
488 /// ])
489 /// .set_class_str(&["data.frame"])
490 /// .set_row_names_str(&["row_a", "row_b", "row_c"]);
491 /// ```
492#[inline]
493pub fn set_row_names_str(self, row_names: &[&str]) -> Self {
494use crate::SEXPTYPE::STRSXP;
495496let n: isize = row_names497 .len()
498 .try_into()
499 .expect("row_names length exceeds isize::MAX");
500unsafe {
501// Protect self across the row.names allocation; see set_class_str.
502let _self_guard = OwnedProtect::new(self.0);
503let names_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
504for (i, name) in row_names.iter().enumerate() {
505let idx: isize = i.try_into().expect("index exceeds isize::MAX");
506 names_vec.get().set_string_elt(idx, SEXP::charsxp(name));
507 }
508self.0.set_row_names(names_vec.get());
509 }
510self511 }
512// endregion
513514 // region: Safe element insertion
515516/// Set an element at the given index, protecting the child during insertion.
517 ///
518 /// This is the safe way to insert a freshly allocated SEXP into a list.
519 /// The child is protected for the duration of the `SET_VECTOR_ELT` call,
520 /// ensuring it cannot be garbage collected.
521 ///
522 /// # Safety
523 ///
524 /// - Must be called from the R main thread
525 /// - `child` must be a valid SEXP
526 /// - `self` must be a valid, protected VECSXP
527 ///
528 /// # Panics
529 ///
530 /// Panics if `idx` is out of bounds.
531 ///
532 /// # Example
533 ///
534 /// ```ignore
535 /// let scope = ProtectScope::new();
536 /// let list = List::from_raw(scope.alloc_vecsxp(n).into_raw());
537 ///
538 /// for i in 0..n {
539 /// let child = Rf_allocVector(REALSXP, 10); // unprotected!
540 /// list.set_elt(i, child); // safe: protects child during insertion
541 /// }
542 /// ```
543#[inline]
544pub unsafe fn set_elt(self, idx: isize, child: SEXP) {
545if !(idx >= 0 && idx < self.len()) {
{ ::core::panicking::panic_fmt(format_args!("index out of bounds")); }
};assert!(idx >= 0 && idx < self.len(), "index out of bounds");
546// Protect child for the duration of SET_VECTOR_ELT.
547 // Once inserted, the child is protected by the parent container.
548 // SAFETY: caller guarantees R main thread and valid SEXPs
549unsafe {
550let _guard = OwnedProtect::new(child);
551self.0.set_vector_elt(idx, child);
552 }
553 }
554555/// Set an element without protecting the child.
556 ///
557 /// # Safety
558 ///
559 /// In addition to the safety requirements of [`set_elt`](Self::set_elt):
560 /// - The caller must ensure `child` is already protected or that no GC
561 /// can occur between child allocation and this call.
562 ///
563 /// Use this for performance when you know the child is already protected
564 /// (e.g., it's a child of another protected container, or you have an
565 /// `OwnedProtect` guard for it).
566#[inline]
567pub unsafe fn set_elt_unchecked(self, idx: isize, child: SEXP) {
568if true {
if !(idx >= 0 && idx < self.len()) {
{ ::core::panicking::panic_fmt(format_args!("index out of bounds")); }
};
};debug_assert!(idx >= 0 && idx < self.len(), "index out of bounds");
569// SAFETY: caller guarantees child is protected and valid
570self.0.set_vector_elt(idx, child);
571 }
572573/// Set an element using a callback that produces the child.
574 ///
575 /// The callback is executed within a protection scope, so any allocations
576 /// it performs are protected until insertion completes.
577 ///
578 /// # Safety
579 ///
580 /// - Must be called from the R main thread
581 /// - `self` must be a valid, protected VECSXP
582 ///
583 /// # Example
584 ///
585 /// ```ignore
586 /// let list = List::from_raw(scope.alloc_vecsxp(n).into_raw());
587 ///
588 /// for i in 0..n {
589 /// list.set_elt_with(i, || {
590 /// let vec = Rf_allocVector(REALSXP, 10);
591 /// fill_vector(vec); // can allocate internally
592 /// vec
593 /// });
594 /// }
595 /// ```
596#[inline]
597pub unsafe fn set_elt_with<F>(self, idx: isize, f: F)
598where
599F: FnOnce() -> SEXP,
600 {
601if !(idx >= 0 && idx < self.len()) {
{ ::core::panicking::panic_fmt(format_args!("index out of bounds")); }
};assert!(idx >= 0 && idx < self.len(), "index out of bounds");
602// SAFETY: caller guarantees R main thread
603unsafe {
604let child = OwnedProtect::new(f());
605self.0.set_vector_elt(idx, child.get());
606 }
607 }
608// endregion
609}
610611// region: ListBuilder - efficient batch list construction
612613use crate::gc_protect::ProtectScope;
614615/// Builder for constructing lists with efficient protection management.
616///
617/// `ListBuilder` holds a reference to a [`ProtectScope`], allowing multiple
618/// elements to be inserted without repeatedly protecting/unprotecting each one.
619/// This is more efficient than using [`List::set_elt`] in a loop.
620///
621/// # Example
622///
623/// ```ignore
624/// unsafe fn build_list(n: isize) -> SEXP {
625/// let scope = ProtectScope::new();
626/// let builder = ListBuilder::new(&scope, n);
627///
628/// for i in 0..n {
629/// // Allocations inside the loop are protected by the scope
630/// let child = scope.alloc_real(10).into_raw();
631/// builder.set(i, child);
632/// }
633///
634/// builder.into_sexp()
635/// }
636/// ```
637pub struct ListBuilder<'a> {
638 list: SEXP,
639 _scope: &'a ProtectScope,
640}
641642impl<'a> ListBuilder<'a> {
643/// Create a new list builder with the given length.
644 ///
645 /// The list is allocated and protected using the provided scope.
646 ///
647 /// # Safety
648 ///
649 /// Must be called from the R main thread.
650#[inline]
651pub unsafe fn new(scope: &'a ProtectScope, len: usize) -> Self {
652// SAFETY: caller guarantees R main thread
653let list = unsafe { scope.alloc_vecsxp(len).into_raw() };
654Self {
655list,
656 _scope: scope,
657 }
658 }
659660/// Create a new list builder via the **unchecked** FFI allocation path.
661 ///
662 /// `_unchecked` twin of [`new`](Self::new): the VECSXP is allocated with
663 /// `Rf_allocVector_unchecked` (see [`ProtectScope::alloc_vecsxp_unchecked`]),
664 /// bypassing the main-thread assertion. Use inside ALTREP callbacks,
665 /// `with_r_unwind_protect`, or `with_r_thread` bodies, and pair element
666 /// insertion with [`set_unchecked`](Self::set_unchecked).
667 ///
668 /// # Safety
669 ///
670 /// Must be called from the R main thread, in a context where the checked-FFI
671 /// assertion is intentionally bypassed (see CLAUDE.md "FFI thread checking").
672#[inline]
673pub unsafe fn new_unchecked(scope: &'a ProtectScope, len: usize) -> Self {
674// SAFETY: caller guarantees R main thread in a checked-bypass context.
675let list = unsafe { scope.alloc_vecsxp_unchecked(len).into_raw() };
676Self {
677list,
678 _scope: scope,
679 }
680 }
681682/// Create a builder wrapping an existing protected list.
683 ///
684 /// # Safety
685 ///
686 /// - Must be called from the R main thread
687 /// - `list` must be a valid, protected VECSXP
688#[inline]
689pub unsafe fn from_protected(scope: &'a ProtectScope, list: SEXP) -> Self {
690Self {
691list,
692 _scope: scope,
693 }
694 }
695696/// Set an element at the given index.
697 ///
698 /// The `child` should be protected by the same scope (or a parent scope).
699 /// Use `scope.protect_raw(...)` before calling this method.
700 ///
701 /// # Safety
702 ///
703 /// - `child` must be a valid SEXP
704 /// - `child` should be protected (typically via the same scope)
705#[inline]
706pub unsafe fn set(&self, idx: isize, child: SEXP) {
707// SAFETY: caller guarantees valid and protected child
708if true {
if !(idx >= 0 && idx < self.list.xlength()) {
::core::panicking::panic("assertion failed: idx >= 0 && idx < self.list.xlength()")
};
};debug_assert!(idx >= 0 && idx < self.list.xlength());
709self.list.set_vector_elt(idx, child);
710 }
711712/// Set an element via the **unchecked** FFI path.
713 ///
714 /// `_unchecked` twin of [`set`](Self::set): inserts with
715 /// `set_vector_elt_unchecked`, bypassing the main-thread assertion. Pair with
716 /// [`new_unchecked`](Self::new_unchecked) inside ALTREP callbacks,
717 /// `with_r_unwind_protect`, or `with_r_thread` bodies.
718 ///
719 /// # Safety
720 ///
721 /// - `child` must be a valid SEXP, already protected (typically by the same
722 /// scope, or by being inserted into this protected parent immediately after
723 /// allocation with no intervening allocation)
724 /// - Must be called from the R main thread, in a checked-bypass context
725#[inline]
726pub unsafe fn set_unchecked(&self, idx: isize, child: SEXP) {
727// SAFETY: caller guarantees valid, protected child in a checked-bypass context.
728if true {
if !(idx >= 0 && idx < self.list.xlength()) {
::core::panicking::panic("assertion failed: idx >= 0 && idx < self.list.xlength()")
};
};debug_assert!(idx >= 0 && idx < self.list.xlength());
729unsafe { self.list.set_vector_elt_unchecked(idx, child) };
730 }
731732/// Set an element, protecting the child within the builder's scope.
733 ///
734 /// This is a convenience method that protects the child and then inserts it.
735 ///
736 /// # Safety
737 ///
738 /// - `child` must be a valid SEXP
739#[inline]
740pub unsafe fn set_protected(&self, idx: isize, child: SEXP) {
741// SAFETY: caller guarantees valid child
742unsafe {
743if true {
if !(idx >= 0 && idx < self.list.xlength()) {
::core::panicking::panic("assertion failed: idx >= 0 && idx < self.list.xlength()")
};
};debug_assert!(idx >= 0 && idx < self.list.xlength());
744let _guard = OwnedProtect::new(child);
745self.list.set_vector_elt(idx, child);
746 }
747 }
748749/// Get the underlying list SEXP.
750#[inline]
751pub fn as_sexp(&self) -> SEXP {
752self.list
753 }
754755/// Convert to a `List` wrapper.
756#[inline]
757pub fn into_list(self) -> List {
758List(self.list)
759 }
760761/// Convert to the underlying SEXP.
762#[inline]
763pub fn into_sexp(self) -> SEXP {
764self.list
765 }
766767/// Get the length of the list.
768#[inline]
769pub fn len(&self) -> isize {
770self.list.xlength()
771 }
772773/// Check if the list is empty.
774#[inline]
775pub fn is_empty(&self) -> bool {
776self.len() == 0
777}
778}
779// endregion
780781mod accumulator;
782mod named;
783784pub use accumulator::*;
785pub use named::*;
786787// region: IntoList and TryFromList traits
788789/// Convert things into an R list.
790pub trait IntoList {
791/// Convert `self` into an R list wrapper.
792fn into_list(self) -> List;
793}
794795/// Fallible conversion from an R list into a Rust value.
796pub trait TryFromList: Sized {
797/// Error returned when conversion fails.
798type Error;
799800/// Attempt to convert an R list wrapper into `Self`.
801fn try_from_list(list: List) -> Result<Self, Self::Error>;
802}
803804// Tuple lists use the same positional representation and batched diagnostics
805// as IntoR/TryFromSexp; no second conversion implementation is needed here.
806macro_rules!impl_tuple_list {
807 ($n:literal, $name:literal; $($T:ident $R:ident $idx:tt),+) => {
808impl<$($T: IntoR),+> IntoList for ($($T,)+) {
809fn into_list(self) -> List {
810 List(self.into_sexp())
811 }
812 }
813814impl<$($T: TryFromSexp),+> TryFromList for ($($T,)+)
815where
816$($T::Error: Into<SexpError>,)+
817 {
818type Error = SexpError;
819820fn try_from_list(list: List) -> Result<Self, Self::Error> {
821Self::try_from_sexp(list.0)
822 }
823 }
824 };
825}
826827impl<A: IntoR> IntoList for (A,) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp> TryFromList for (A,) where A::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR> IntoList for (A, B) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp> TryFromList for (A, B) where
A::Error: Into<SexpError>, B::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR> IntoList for (A, B, C) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp> TryFromList for (A, B, C)
where A::Error: Into<SexpError>, B::Error: Into<SexpError>,
C::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR> IntoList for (A, B, C, D) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp>
TryFromList for (A, B, C, D) where A::Error: Into<SexpError>,
B::Error: Into<SexpError>, C::Error: Into<SexpError>,
D::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR> IntoList for
(A, B, C, D, E) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp> TryFromList for (A, B, C, D, E) where
A::Error: Into<SexpError>, B::Error: Into<SexpError>,
C::Error: Into<SexpError>, D::Error: Into<SexpError>,
E::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR> IntoList for
(A, B, C, D, E, F) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp> TryFromList for (A, B, C, D, E, F) where
A::Error: Into<SexpError>, B::Error: Into<SexpError>,
C::Error: Into<SexpError>, D::Error: Into<SexpError>,
E::Error: Into<SexpError>, F::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR>
IntoList for (A, B, C, D, E, F, G) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp> TryFromList for
(A, B, C, D, E, F, G) where A::Error: Into<SexpError>,
B::Error: Into<SexpError>, C::Error: Into<SexpError>,
D::Error: Into<SexpError>, E::Error: Into<SexpError>,
F::Error: Into<SexpError>, G::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR,
H: IntoR> IntoList for (A, B, C, D, E, F, G, H) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp, H: TryFromSexp>
TryFromList for (A, B, C, D, E, F, G, H) where A::Error: Into<SexpError>,
B::Error: Into<SexpError>, C::Error: Into<SexpError>,
D::Error: Into<SexpError>, E::Error: Into<SexpError>,
F::Error: Into<SexpError>, G::Error: Into<SexpError>,
H::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR,
H: IntoR, I: IntoR> IntoList for (A, B, C, D, E, F, G, H, I) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp, H: TryFromSexp,
I: TryFromSexp> TryFromList for (A, B, C, D, E, F, G, H, I) where
A::Error: Into<SexpError>, B::Error: Into<SexpError>,
C::Error: Into<SexpError>, D::Error: Into<SexpError>,
E::Error: Into<SexpError>, F::Error: Into<SexpError>,
G::Error: Into<SexpError>, H::Error: Into<SexpError>,
I::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR,
H: IntoR, I: IntoR, J: IntoR> IntoList for (A, B, C, D, E, F, G, H, I, J)
{
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp, H: TryFromSexp,
I: TryFromSexp, J: TryFromSexp> TryFromList for
(A, B, C, D, E, F, G, H, I, J) where A::Error: Into<SexpError>,
B::Error: Into<SexpError>, C::Error: Into<SexpError>,
D::Error: Into<SexpError>, E::Error: Into<SexpError>,
F::Error: Into<SexpError>, G::Error: Into<SexpError>,
H::Error: Into<SexpError>, I::Error: Into<SexpError>,
J::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR,
H: IntoR, I: IntoR, J: IntoR, K: IntoR> IntoList for
(A, B, C, D, E, F, G, H, I, J, K) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp, H: TryFromSexp,
I: TryFromSexp, J: TryFromSexp, K: TryFromSexp> TryFromList for
(A, B, C, D, E, F, G, H, I, J, K) where A::Error: Into<SexpError>,
B::Error: Into<SexpError>, C::Error: Into<SexpError>,
D::Error: Into<SexpError>, E::Error: Into<SexpError>,
F::Error: Into<SexpError>, G::Error: Into<SexpError>,
H::Error: Into<SexpError>, I::Error: Into<SexpError>,
J::Error: Into<SexpError>, K::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}
impl<A: IntoR, B: IntoR, C: IntoR, D: IntoR, E: IntoR, F: IntoR, G: IntoR,
H: IntoR, I: IntoR, J: IntoR, K: IntoR, L: IntoR> IntoList for
(A, B, C, D, E, F, G, H, I, J, K, L) {
fn into_list(self) -> List { List(self.into_sexp()) }
}
impl<A: TryFromSexp, B: TryFromSexp, C: TryFromSexp, D: TryFromSexp,
E: TryFromSexp, F: TryFromSexp, G: TryFromSexp, H: TryFromSexp,
I: TryFromSexp, J: TryFromSexp, K: TryFromSexp, L: TryFromSexp>
TryFromList for (A, B, C, D, E, F, G, H, I, J, K, L) where
A::Error: Into<SexpError>, B::Error: Into<SexpError>,
C::Error: Into<SexpError>, D::Error: Into<SexpError>,
E::Error: Into<SexpError>, F::Error: Into<SexpError>,
G::Error: Into<SexpError>, H::Error: Into<SexpError>,
I::Error: Into<SexpError>, J::Error: Into<SexpError>,
K::Error: Into<SexpError>, L::Error: Into<SexpError> {
type Error = SexpError;
fn try_from_list(list: List) -> Result<Self, Self::Error> {
Self::try_from_sexp(list.0)
}
}crate::tuple_macros::for_each_tuple!(impl_tuple_list);
828829impl<T: IntoR> IntoListfor Vec<T> {
830fn into_list(self) -> List {
831// Allocate + protect the parent first, then call `into_sexp()` per
832 // element and write straight into the parent. Pre-collecting elements
833 // into `Vec<SEXP>` would leave them unrooted across allocations — same
834 // UAF shape as the columnar `Generic` buffer (PR #424 / issue #307).
835let n: isize = self836 .len()
837 .try_into()
838 .expect("list length exceeds isize::MAX");
839unsafe {
840let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
841for (i, val) in self.into_iter().enumerate() {
842let idx: isize = i.try_into().expect("index exceeds isize::MAX");
843 list.get().set_vector_elt(idx, val.into_sexp());
844 }
845List(list.get())
846 }
847 }
848}
849850impl<T> TryFromListfor Vec<T>
851where
852T: TryFromSexp<Error = SexpError>,
853{
854type Error = SexpError;
855856fn try_from_list(list: List) -> Result<Self, Self::Error> {
857let expected: usize = list858 .len()
859 .try_into()
860 .expect("list length must be non-negative");
861let mut out = Vec::with_capacity(expected);
862for i in 0..expected {
863let idx: isize = i.try_into().expect("index exceeds isize::MAX");
864let sexp = list.get(idx).ok_or_else(|| {
865 SexpError::from(SexpLengthError {
866 expected,
867 actual: i,
868 })
869 })?;
870 out.push(TryFromSexp::try_from_sexp(sexp)?);
871 }
872Ok(out)
873 }
874}
875876// endregion
877878// region: HashMap conversions
879880impl<K, V> IntoListfor HashMap<K, V>
881where
882K: AsRef<str>,
883 V: IntoR,
884{
885fn into_list(self) -> List {
886let pairs: Vec<(K, V)> = self.into_iter().collect();
887List::from_pairs(pairs)
888 }
889}
890891/// Keys are the element names; an element without a usable name (no `names`
892/// attribute, `NA`, or a name that is not text, see [`text_name`]) is keyed
893/// by its 0-based position, and
894/// empty names share the key `""` (the last one wins). A non-empty name that
895/// appears more than once is an error ([`SexpError::DuplicateName`]), as for
896/// the `TryFromSexp` map conversion.
897impl<V> TryFromListfor HashMap<String, V>
898where
899V: TryFromSexp<Error = SexpError>,
900{
901type Error = SexpError;
902903fn try_from_list(list: List) -> Result<Self, Self::Error> {
904// A repeated name would leave only one of its values in the map.
905if let Some(name) = list.first_duplicate_name() {
906return Err(SexpError::DuplicateName(name));
907 }
908let n: usize = list909 .len()
910 .try_into()
911 .expect("list length must be non-negative");
912let names_sexp = list.names();
913let mut map = HashMap::with_capacity(n);
914915for i in 0..n {
916let idx: isize = i.try_into().expect("index exceeds isize::MAX");
917let sexp = list.get(idx).ok_or_else(|| {
918 SexpError::from(SexpLengthError {
919 expected: n,
920 actual: i,
921 })
922 })?;
923let value: V = TryFromSexp::try_from_sexp(sexp)?;
924925let key = if let Some(names) = names_sexp {
926 text_name(names.string_elt(idx)).map_or_else(|| ::alloc::__export::must_use({ ::alloc::fmt::format(format_args!("{0}", i)) })format!("{i}"), str::to_string)
927 } else {
928::alloc::__export::must_use({ ::alloc::fmt::format(format_args!("{0}", i)) })format!("{i}")929 };
930931 map.insert(key, value);
932 }
933Ok(map)
934 }
935}
936// endregion
937938// region: BTreeMap conversions
939940impl<K, V> IntoListfor BTreeMap<K, V>
941where
942K: AsRef<str>,
943 V: IntoR,
944{
945fn into_list(self) -> List {
946let pairs: Vec<(K, V)> = self.into_iter().collect();
947List::from_pairs(pairs)
948 }
949}
950951/// Keys are the element names; an element without a usable name (no `names`
952/// attribute, `NA`, or a name that is not text, see [`text_name`]) is keyed
953/// by its 0-based position, and
954/// empty names share the key `""` (the last one wins). A non-empty name that
955/// appears more than once is an error ([`SexpError::DuplicateName`]), as for
956/// the `TryFromSexp` map conversion.
957impl<V> TryFromListfor BTreeMap<String, V>
958where
959V: TryFromSexp<Error = SexpError>,
960{
961type Error = SexpError;
962963fn try_from_list(list: List) -> Result<Self, Self::Error> {
964// A repeated name would leave only one of its values in the map.
965if let Some(name) = list.first_duplicate_name() {
966return Err(SexpError::DuplicateName(name));
967 }
968let n: usize = list969 .len()
970 .try_into()
971 .expect("list length must be non-negative");
972let names_sexp = list.names();
973let mut map = BTreeMap::new();
974975for i in 0..n {
976let idx: isize = i.try_into().expect("index exceeds isize::MAX");
977let sexp = list.get(idx).ok_or_else(|| {
978 SexpError::from(SexpLengthError {
979 expected: n,
980 actual: i,
981 })
982 })?;
983let value: V = TryFromSexp::try_from_sexp(sexp)?;
984985let key = if let Some(names) = names_sexp {
986 text_name(names.string_elt(idx)).map_or_else(|| ::alloc::__export::must_use({ ::alloc::fmt::format(format_args!("{0}", i)) })format!("{i}"), str::to_string)
987 } else {
988::alloc::__export::must_use({ ::alloc::fmt::format(format_args!("{0}", i)) })format!("{i}")989 };
990991 map.insert(key, value);
992 }
993Ok(map)
994 }
995}
996// endregion
997998// region: HashSet conversions (unnamed list <-> set)
9991000impl<T> IntoListfor HashSet<T>
1001where
1002T: IntoR,
1003{
1004fn into_list(self) -> List {
1005let values: Vec<T> = self.into_iter().collect();
1006values.into_list()
1007 }
1008}
10091010impl<T> TryFromListfor HashSet<T>
1011where
1012T: TryFromSexp<Error = SexpError> + Eq + Hash,
1013{
1014type Error = SexpError;
10151016fn try_from_list(list: List) -> Result<Self, Self::Error> {
1017let vec: Vec<T> = TryFromList::try_from_list(list)?;
1018Ok(vec.into_iter().collect())
1019 }
1020}
1021// endregion
10221023// region: BTreeSet conversions (unnamed list <-> set)
10241025impl<T> IntoListfor BTreeSet<T>
1026where
1027T: IntoR,
1028{
1029fn into_list(self) -> List {
1030let values: Vec<T> = self.into_iter().collect();
1031values.into_list()
1032 }
1033}
10341035impl<T> TryFromListfor BTreeSet<T>
1036where
1037T: TryFromSexp<Error = SexpError> + Ord,
1038{
1039type Error = SexpError;
10401041fn try_from_list(list: List) -> Result<Self, Self::Error> {
1042let vec: Vec<T> = TryFromList::try_from_list(list)?;
1043Ok(vec.into_iter().collect())
1044 }
1045}
10461047impl List {
1048/// Build a list from `(name, value)` pairs, setting `names` in one pass.
1049pub fn from_pairs<N, T>(pairs: Vec<(N, T)>) -> Self
1050where
1051N: AsRef<str>,
1052 T: IntoR,
1053 {
1054// Allocate + protect the parent list and names before calling
1055 // `into_sexp()` on each value. Pre-collecting `Vec<(N, SEXP)>` would
1056 // leave the value SEXPs unrooted across subsequent `into_sexp()` and
1057 // the names allocation — same UAF shape as #307.
1058let n: isize = pairs1059 .len()
1060 .try_into()
1061 .expect("pairs length exceeds isize::MAX");
1062unsafe {
1063let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1064let names = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
1065for (i, (name, val)) in pairs.into_iter().enumerate() {
1066let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1067 list.get().set_vector_elt(idx, val.into_sexp());
1068 names
1069 .get()
1070 .set_string_elt(idx, SEXP::charsxp(name.as_ref()));
1071 }
1072list.get().set_names(names.get());
1073List(list.get())
1074 }
1075 }
10761077/// Build an unnamed list from values.
1078 ///
1079 /// Use this for tuple-like structures where positional access is more natural.
1080 ///
1081 /// # Example
1082 ///
1083 /// ```ignore
1084 /// let list = List::from_values(vec![1i32, 2i32, 3i32]);
1085 /// // R: list(1L, 2L, 3L) - accessed as [[1]], [[2]], [[3]]
1086 /// ```
1087pub fn from_values<T: IntoR>(values: Vec<T>) -> Self {
1088values.into_list()
1089 }
10901091/// Build an unnamed list from pre-converted SEXPs.
1092 ///
1093 /// # Safety Note
1094 ///
1095 /// The input SEXPs should already be protected or be children of protected
1096 /// containers. This function protects the list during construction.
1097pub fn from_raw_values(values: Vec<SEXP>) -> Self {
1098let n: isize = values1099 .len()
1100 .try_into()
1101 .expect("values length exceeds isize::MAX");
1102unsafe {
1103// Protect list during construction. SET_VECTOR_ELT doesn't allocate,
1104 // but we protect defensively in case this code is modified later.
1105let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1106for (i, val) in values.into_iter().enumerate() {
1107let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1108 list.get().set_vector_elt(idx, val);
1109 }
1110List(list.get())
1111 }
1112 }
11131114/// Build an atomic vector from homogeneous length-1 scalar SEXPs.
1115 ///
1116 /// If all elements are length-1 scalars of the same coalesceable type
1117 /// (INTSXP, REALSXP, LGLSXP, STRSXP), returns that atomic vector.
1118 /// Otherwise returns a VECSXP (generic list).
1119 ///
1120 /// This is the canonical entry point for both `DataFrame::into_data_frame`
1121 /// (column building) and `SeqSerializer::end` (sequence coalescing).
1122 ///
1123 /// # Safety Note
1124 ///
1125 /// The input SEXPs should already be protected or be children of protected
1126 /// containers.
1127pub fn from_scalars_or_list(elements: &[SEXP]) -> Self {
1128use crate::SEXPTYPE;
1129use crate::into_r::alloc_r_vector;
11301131if elements.is_empty() {
1132return Self::from_raw_values(Vec::new());
1133 }
11341135let first_type = elements[0].type_of();
1136let all_scalar_same_type = elements1137 .iter()
1138 .all(|&e| e.xlength() == 1 && e.type_of() == first_type);
11391140if !all_scalar_same_type {
1141return Self::from_raw_values(elements.to_vec());
1142 }
11431144let n = elements.len();
1145let sexp = match first_type {
1146// For native types: allocate R vector, get mutable slice, read source
1147 // scalars via as_slice()[0] — no per-element FFI calls.
1148SEXPTYPE::INTSXP => unsafe {
1149let (v, dst) = alloc_r_vector::<i32>(n);
1150for (slot, &elem) in dst.iter_mut().zip(elements.iter()) {
1151*slot = *elem.as_slice::<i32>().first().expect("scalar has length 1");
1152 }
1153v1154 },
1155 SEXPTYPE::REALSXP => unsafe {
1156let (v, dst) = alloc_r_vector::<f64>(n);
1157for (slot, &elem) in dst.iter_mut().zip(elements.iter()) {
1158*slot = *elem.as_slice::<f64>().first().expect("scalar has length 1");
1159 }
1160v1161 },
1162 SEXPTYPE::LGLSXP => unsafe {
1163let (v, dst) = alloc_r_vector::<crate::RLogical>(n);
1164for (slot, &elem) in dst.iter_mut().zip(elements.iter()) {
1165*slot = *elem
1166 .as_slice::<crate::RLogical>()
1167 .first()
1168 .expect("scalar has length 1");
1169 }
1170v1171 },
1172// STRSXP elements are CHARSXPs — must use SET_STRING_ELT (no slice access).
1173SEXPTYPE::STRSXP => unsafe {
1174let v = OwnedProtect::new(sys::Rf_allocVector(SEXPTYPE::STRSXP, nas isize));
1175for (i, &elem) in elements.iter().enumerate() {
1176let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1177 v.get().set_string_elt(idx, elem.string_elt(0));
1178 }
1179v.get()
1180 },
1181_ => return Self::from_raw_values(elements.to_vec()),
1182 };
1183List(sexp)
1184 }
11851186/// Build a list from `(name, SEXP)` pairs (heterogeneous-friendly).
1187 ///
1188 /// # Safety Note
1189 ///
1190 /// The input SEXPs should already be protected or be children of protected
1191 /// containers. This function protects the list and names vector during
1192 /// construction.
1193pub fn from_raw_pairs<N>(pairs: Vec<(N, SEXP)>) -> Self
1194where
1195N: AsRef<str>,
1196 {
1197let n: isize = pairs1198 .len()
1199 .try_into()
1200 .expect("pairs length exceeds isize::MAX");
1201unsafe {
1202// CRITICAL: Both list and names must be protected because
1203 // Rf_mkCharLenCE can allocate and trigger GC in the loop below.
1204let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1205let names = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
1206for (i, (name, val)) in pairs.into_iter().enumerate() {
1207let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1208 list.get().set_vector_elt(idx, val);
12091210let s = name.as_ref();
1211// SEXP::charsxp allocates - list and names must be protected!
1212names.get().set_string_elt(idx, SEXP::charsxp(s));
1213 }
1214list.get().set_names(names.get());
1215List(list.get())
1216 }
1217 }
12181219/// Build an empty named-list SEXP (zero elements, `names` attribute set).
1220 ///
1221 /// Equivalent to [`Self::from_raw_pairs`]`(vec![])`, but avoids the
1222 /// `Vec<(&str, SEXP)>` type annotation that Rust requires at empty-vector
1223 /// callsites where type inference cannot resolve the element type.
1224 ///
1225 /// Codegen paths that emit an empty `from_raw_pairs` call (e.g. unit-variant
1226 /// partitions in `#[derive(DataFrameRow)]`) use this helper so that a future
1227 /// signature change to `from_raw_pairs` only needs to be updated in one
1228 /// place.
1229#[must_use]
1230pub fn from_raw_pairs_empty() -> Self {
1231Self::from_raw_pairs(Vec::<(&str, SEXP)>::new())
1232 }
1233}
12341235impl IntoRfor List {
1236type Error = std::convert::Infallible;
1237fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1238Ok(self.into_sexp())
1239 }
1240unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1241self.try_into_sexp()
1242 }
1243#[inline]
1244fn into_sexp(self) -> SEXP {
1245self.0
1246}
1247}
12481249impl IntoRfor ListMut {
1250type Error = std::convert::Infallible;
1251fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1252Ok(self.into_sexp())
1253 }
1254unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1255self.try_into_sexp()
1256 }
1257#[inline]
1258fn into_sexp(self) -> SEXP {
1259self.0
1260}
1261}
12621263/// `Some(list)` → the list, `None` → `NULL`: the inverse of
1264/// `TryFromSexp for Option<List>`.
1265impl IntoRfor Option<List> {
1266type Error = std::convert::Infallible;
1267fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1268Ok(self.into_sexp())
1269 }
1270unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1271self.try_into_sexp()
1272 }
1273#[inline]
1274fn into_sexp(self) -> SEXP {
1275self.map_or_else(SEXP::nil, |list| list.0)
1276 }
1277}
12781279/// `Some(list)` → the list, `None` → `NULL`: the inverse of
1280/// `TryFromSexp for Option<ListMut>`.
1281impl IntoRfor Option<ListMut> {
1282type Error = std::convert::Infallible;
1283fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1284Ok(self.into_sexp())
1285 }
1286unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1287self.try_into_sexp()
1288 }
1289#[inline]
1290fn into_sexp(self) -> SEXP {
1291self.map_or_else(SEXP::nil, |list| list.0)
1292 }
1293}
12941295/// Build an R list-column (VECSXP) from values converted one at a time through
1296/// [`IntoList`].
1297///
1298/// The column is allocated and protected first; each value's list is stored in
1299/// it as soon as it is built, so no list is ever unrooted while the next one
1300/// allocates. Collecting a `Vec<List>` first and converting that would leave
1301/// every earlier list unrooted across the later allocations (#1748).
1302///
1303/// Used by `#[derive(DataFrameRow)]` for `#[dataframe(as_list)]` struct-typed
1304/// fields.
1305#[doc(hidden)]
1306pub fn into_list_column<T: IntoList>(values: Vec<T>) -> SEXP {
1307let n: isize = values1308 .len()
1309 .try_into()
1310 .expect("list-column length exceeds isize::MAX");
1311unsafe {
1312let out = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1313for (i, value) in values.into_iter().enumerate() {
1314let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1315// No allocation between building the list and storing it.
1316out.get().set_vector_elt(idx, value.into_list().0);
1317 }
1318out.get()
1319 }
1320}
13211322/// [`into_list_column`] for optional cells: `None` becomes `NULL`.
1323#[doc(hidden)]
1324pub fn into_option_list_column<T: IntoList>(values: Vec<Option<T>>) -> SEXP {
1325let n: isize = values1326 .len()
1327 .try_into()
1328 .expect("list-column length exceeds isize::MAX");
1329unsafe {
1330// VECSXP slots start as R_NilValue, so `None` cells need no write.
1331let out = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1332for (i, value) in values.into_iter().enumerate() {
1333if let Some(value) = value {
1334let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1335 out.get().set_vector_elt(idx, value.into_list().0);
1336 }
1337 }
1338out.get()
1339 }
1340}
13411342/// Convert a `Vec<List>` to an R list-column (VECSXP).
1343///
1344/// Each element becomes an R list in the output VECSXP. The elements must be
1345/// rooted by the caller (for example, elements of an argument list): this
1346/// allocates the column first. To build the lists as you go, use
1347/// [`into_list_column`].
1348impl IntoRfor Vec<List> {
1349type Error = std::convert::Infallible;
1350fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1351Ok(self.into_sexp())
1352 }
1353unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1354self.try_into_sexp()
1355 }
1356fn into_sexp(self) -> SEXP {
1357unsafe {
1358use crate::gc_protect::OwnedProtect;
1359use crate::sys::Rf_allocVector;
1360use crate::{SEXPTYPE, SexpExtas _};
1361let n = self.len() as crate::R_xlen_t;
1362// OwnedProtect guards `out` across the per-element fill; its Drop
1363 // issues the matching UNPROTECT(1) (RAII — count balanced by
1364 // construction).
1365let out = OwnedProtect::new(Rf_allocVector(SEXPTYPE::VECSXP, n));
1366for (i, list) in self.into_iter().enumerate() {
1367 out.get().set_vector_elt(i as crate::R_xlen_t, list.0);
1368 }
1369*out1370 }
1371 }
1372}
13731374/// Convert a `Vec<Option<List>>` to an R list-column (VECSXP).
1375///
1376/// `Some(list)` elements are placed directly as list elements; `None` elements
1377/// become `R_NilValue`. As with `Vec<List>`, the elements must be rooted by
1378/// the caller; [`into_option_list_column`] builds them as it goes.
1379impl IntoRfor Vec<Option<List>> {
1380type Error = std::convert::Infallible;
1381fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1382Ok(self.into_sexp())
1383 }
1384unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1385self.try_into_sexp()
1386 }
1387fn into_sexp(self) -> SEXP {
1388unsafe {
1389use crate::gc_protect::OwnedProtect;
1390use crate::sys::Rf_allocVector;
1391use crate::{SEXPTYPE, SexpExtas _};
1392let n = self.len() as crate::R_xlen_t;
1393// VECSXP slots are zero-initialised to R_NilValue by Rf_allocVector,
1394 // so None elements require no explicit fill. OwnedProtect guards
1395 // `out` across the fill and issues the matching UNPROTECT(1) on Drop.
1396let out = OwnedProtect::new(Rf_allocVector(SEXPTYPE::VECSXP, n));
1397for (i, opt) in self.into_iter().enumerate() {
1398if let Some(list) = opt {
1399 out.get().set_vector_elt(i as crate::R_xlen_t, list.0);
1400 }
1401 }
1402*out1403 }
1404 }
1405}
14061407/// A `List` reads any R list, whatever its names.
1408///
1409/// Accepts a `VECSXP` only; anything else is a [`SexpTypeError`]. A pairlist
1410/// (`LISTSXP`, such as `formals(f)` or `pairlist(...)`) is refused, not
1411/// coerced (#1866): the coerced copy would be a new object that nothing
1412/// roots, since `List` is a `Copy` view, so the first allocation in the
1413/// function could free it. The caller converts with `as.list()`, and the
1414/// argument error says so.
1415///
1416/// Names are not checked: R allows a name to appear more than once
1417/// (`list(a = 1, a = 2)`), and so does `List`. A function that needs unique
1418/// names checks with [`List::first_duplicate_name`].
1419impl TryFromSexpfor List {
1420type Error = SexpTypeError;
14211422fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1423let actual = sexp.type_of();
1424if actual == VECSXP {
1425Ok(List(sexp))
1426 } else {
1427Err(SexpTypeError {
1428 expected: VECSXP,
1429actual,
1430 })
1431 }
1432 }
1433}
14341435impl TryFromSexpfor Option<List> {
1436type Error = SexpError;
14371438fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1439if sexp == SEXP::nil() {
1440return Ok(None);
1441 }
1442Ok(Some(List::try_from_sexp(sexp)?))
1443 }
1444}
14451446/// One element of a list of lists: a `VECSXP`. A pairlist element is refused,
1447/// as `List` refuses a pairlist: a coerced copy would be a new object that
1448/// nothing roots while the rest of the list is read.
1449fn list_element(elem: SEXP) -> Result<List, SexpError> {
1450let actual = elem.type_of();
1451if actual == VECSXP {
1452Ok(List(elem))
1453 } else {
1454Err(SexpTypeError {
1455 expected: VECSXP,
1456actual,
1457 }
1458 .into())
1459 }
1460}
14611462/// A list of lists (a list of R objects, such as model objects), read element
1463/// by element (#1837).
1464///
1465/// The argument must be a list (`VECSXP`), and each element a list too. A
1466/// pairlist is refused at either level, as for a `List` argument (#1866).
1467/// Every element that fails is reported in one
1468/// error, with its position as R counts it: `expected list, got numeric
1469/// (elements 2, 3)`. The elements stay rooted by the argument list.
1470///
1471/// A `Vec` of a `#[derive(TryFromSexp)]` newtype over `List` reads through
1472/// this, and runs the newtype's check (`#[try_from_sexp(validate = ...)]`) on
1473/// each element, where each object keeps its class, not on the outer list.
1474impl TryFromSexpfor Vec<List> {
1475type Error = SexpError;
14761477#[inline]
1478fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1479Self::__mx_try_from_sexp_with_check(sexp, &no_element_check)
1480 }
14811482#[inline]
1483unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
1484Self::try_from_sexp(sexp)
1485 }
14861487/// `check` runs on each element, before the element is read.
1488fn __mx_try_from_sexp_with_check(
1489 sexp: SEXP,
1490 check: &ElementCheck<'_>,
1491 ) -> Result<Self, SexpError> {
1492map_vecsxp_batched(sexp, |elem| {
1493 check(elem)?;
1494list_element(elem)
1495 })
1496 }
14971498#[inline]
1499unsafe fn __mx_try_from_sexp_unchecked_with_check(
1500 sexp: SEXP,
1501 check: &ElementCheck<'_>,
1502 ) -> Result<Self, SexpError> {
1503Self::__mx_try_from_sexp_with_check(sexp, check)
1504 }
1505}
15061507/// A list of lists and `NULL`s, read element by element: a `NULL` element is
1508/// `None`, any other element is read as for `Vec<List>`, with every failing
1509/// element reported in one error.
1510///
1511/// For a `Vec<Option<T>>` of a newtype over `List`, the newtype's check runs
1512/// on each element but `NULL`, which stays "not given", as for `Option<T>`.
1513impl TryFromSexpfor Vec<Option<List>> {
1514type Error = SexpError;
15151516#[inline]
1517fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1518Self::__mx_try_from_sexp_with_check(sexp, &no_element_check)
1519 }
15201521#[inline]
1522unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
1523Self::try_from_sexp(sexp)
1524 }
15251526/// `check` runs on each element but `NULL`, before the element is read.
1527fn __mx_try_from_sexp_with_check(
1528 sexp: SEXP,
1529 check: &ElementCheck<'_>,
1530 ) -> Result<Self, SexpError> {
1531map_vecsxp_batched(sexp, |elem| {
1532if elem.type_of() == NILSXP {
1533return Ok(None);
1534 }
1535 check(elem)?;
1536list_element(elem).map(Some)
1537 })
1538 }
15391540#[inline]
1541unsafe fn __mx_try_from_sexp_unchecked_with_check(
1542 sexp: SEXP,
1543 check: &ElementCheck<'_>,
1544 ) -> Result<Self, SexpError> {
1545Self::__mx_try_from_sexp_with_check(sexp, check)
1546 }
1547}
15481549impl TryFromSexpfor Option<ListMut> {
1550type Error = SexpError;
15511552fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1553if sexp == SEXP::nil() {
1554return Ok(None);
1555 }
1556let list = ListMut::try_from_sexp(sexp)?;
1557Ok(Some(list))
1558 }
1559}
15601561impl TryFromSexpfor ListMut {
1562type Error = SexpError;
15631564fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1565let actual = sexp.type_of();
1566if actual != VECSXP {
1567return Err(SexpTypeError {
1568 expected: VECSXP,
1569actual,
1570 }
1571 .into());
1572 }
1573Ok(ListMut(sexp))
1574 }
1575}
1576// endregion