Skip to main content

miniextendr_api/
list.rs

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
21
22mod named_builder;
23pub use named_builder::{BuiltList, NamedListBuilder};
24
25use crate::SEXPTYPE::{NILSXP, STRSXP, VECSXP};
26use crate::from_r::{
27    ElementCheck, SexpError, SexpLengthError, SexpTypeError, TryFromSexp, map_vecsxp_batched,
28    no_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;
36
37/// 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);
50
51/// 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);
57
58/// 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> {
62    if charsxp == SEXP::na_string() {
63        return None;
64    }
65    // SAFETY: a non-NA CHARSXP of a names attribute the caller roots.
66    unsafe { try_charsxp_to_str(charsxp) }.ok()
67}
68
69impl 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]
74    pub fn is_list(self) -> bool {
75        <SEXP as crate::SexpExt>::is_list(&self.0)
76    }
77
78    /// 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]
85    pub const unsafe fn from_raw(sexp: SEXP) -> Self {
86        List(sexp)
87    }
88
89    /// Get the underlying `SEXP`.
90    #[inline]
91    pub const fn as_sexp(self) -> SEXP {
92        self.0
93    }
94
95    /// Length of the list (number of elements).
96    #[inline]
97    pub fn len(self) -> isize {
98        self.0.xlength()
99    }
100
101    /// Returns true if the list is empty.
102    #[inline]
103    pub fn is_empty(self) -> bool {
104        self.len() == 0
105    }
106
107    /// Get raw SEXP element at 0-based index. Returns `None` if out of bounds.
108    #[inline]
109    pub fn get(self, idx: isize) -> Option<SEXP> {
110        if idx < 0 || idx >= self.len() {
111            return None;
112        }
113        Some(self.0.vector_elt(idx))
114    }
115
116    /// 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]
125    pub fn get_index<T>(self, idx: isize) -> Option<T>
126    where
127        T: TryFromSexp,
128    {
129        let sexp = self.get(idx)?;
130        T::try_from_sexp(sexp).ok()
131    }
132
133    /// 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.
146    pub(crate) fn text_names(self) -> impl Iterator<Item = (isize, &'static str)> {
147        let names = self.names();
148        let 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    }
151
152    /// 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.
160    pub fn get_named_sexp(self, name: &str) -> Option<SEXP> {
161        self.text_names()
162            .find(|&(_, s)| s == name)
163            .map(|(i, _)| self.0.vector_elt(i))
164    }
165
166    /// 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.
188    pub fn first_duplicate_name(self) -> Option<String> {
189        let mut seen = HashSet::new();
190        self.text_names()
191            .map(|(_, s)| s)
192            .filter(|s| !s.is_empty())
193            .find(|s| !seen.insert(*s))
194            .map(str::to_owned)
195    }
196
197    /// 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)]
210    pub fn __mx_field_positions<const N: usize>(
211        self,
212        sorted_fields: [&str; N],
213    ) -> Result<[Option<isize>; N], SexpError> {
214        if 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");
215        let mut positions = [None; N];
216        for (i, name) in self.text_names() {
217            if let Ok(k) = sorted_fields.binary_search(&name) {
218                if positions[k].is_some() {
219                    return Err(SexpError::DuplicateName(name.to_owned()));
220                }
221                positions[k] = Some(i);
222            }
223        }
224        Ok(positions)
225    }
226
227    /// 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.
234    pub fn get_named<T>(self, name: &str) -> Option<T>
235    where
236        T: TryFromSexp,
237    {
238        let sexp = self.get_named_sexp(name)?;
239        T::try_from_sexp(sexp).ok()
240    }
241
242    // region: Attribute getters (equivalent to R's GET_* macros)
243
244    /// Get an arbitrary attribute by symbol, returning `None` for `R_NilValue`.
245    #[inline]
246    fn get_attr_opt(self, name: SEXP) -> Option<SEXP> {
247        let attr = self.0.get_attr(name);
248        if attr.is_nil() { None } else { Some(attr) }
249    }
250
251    /// Get the `names` attribute if present.
252    #[inline]
253    pub fn names(self) -> Option<SEXP> {
254        self.get_attr_opt(SEXP::names_symbol())
255    }
256
257    /// Get the `class` attribute if present.
258    #[inline]
259    pub fn get_class(self) -> Option<SEXP> {
260        self.get_attr_opt(SEXP::class_symbol())
261    }
262
263    /// Get the `dim` attribute if present.
264    #[inline]
265    pub fn get_dim(self) -> Option<SEXP> {
266        self.get_attr_opt(SEXP::dim_symbol())
267    }
268
269    /// Get the `dimnames` attribute if present.
270    #[inline]
271    pub fn get_dimnames(self) -> Option<SEXP> {
272        self.get_attr_opt(SEXP::dimnames_symbol())
273    }
274
275    /// Get row names from the `dimnames` attribute.
276    #[inline]
277    pub fn get_rownames(self) -> Option<SEXP> {
278        let dimnames = self.0.get_dimnames();
279        if dimnames.is_nil() {
280            return None;
281        }
282        let rownames = unsafe { sys::Rf_GetRowNames(dimnames) };
283        if rownames.is_nil() {
284            None
285        } else {
286            Some(rownames)
287        }
288    }
289
290    /// Get column names from the `dimnames` attribute.
291    #[inline]
292    pub fn get_colnames(self) -> Option<SEXP> {
293        let dimnames = self.0.get_dimnames();
294        if dimnames.is_nil() {
295            return None;
296        }
297        let colnames = unsafe { sys::Rf_GetColNames(dimnames) };
298        if colnames.is_nil() {
299            None
300        } else {
301            Some(colnames)
302        }
303    }
304
305    /// Get the `levels` attribute if present (for factors).
306    #[inline]
307    pub fn get_levels(self) -> Option<SEXP> {
308        self.get_attr_opt(SEXP::levels_symbol())
309    }
310
311    /// Get the `tsp` attribute if present (for time series).
312    #[inline]
313    pub fn get_tsp(self) -> Option<SEXP> {
314        self.get_attr_opt(SEXP::tsp_symbol())
315    }
316    // endregion
317
318    // region: Attribute setters (equivalent to R's SET_* macros)
319
320    /// Set the `names` attribute; returns the same list for chaining.
321    ///
322    /// Equivalent to R's `SET_NAMES(x, n)`.
323    #[inline]
324    pub fn set_names(self, names: SEXP) -> Self {
325        self.0.set_names(names);
326        self
327    }
328
329    /// Set the `class` attribute; returns the same list for chaining.
330    ///
331    /// Equivalent to R's `SET_CLASS(x, n)`.
332    #[inline]
333    pub fn set_class(self, class: SEXP) -> Self {
334        self.0.set_class(class);
335        self
336    }
337
338    /// Set the `dim` attribute; returns the same list for chaining.
339    ///
340    /// Equivalent to R's `SET_DIM(x, n)`.
341    #[inline]
342    pub fn set_dim(self, dim: SEXP) -> Self {
343        self.0.set_dim(dim);
344        self
345    }
346
347    /// Set the `dimnames` attribute; returns the same list for chaining.
348    ///
349    /// Equivalent to R's `SET_DIMNAMES(x, n)`.
350    #[inline]
351    pub fn set_dimnames(self, dimnames: SEXP) -> Self {
352        self.0.set_dimnames(dimnames);
353        self
354    }
355
356    /// Set the `levels` attribute; returns the same list for chaining.
357    ///
358    /// Equivalent to R's `SET_LEVELS(x, l)`.
359    #[inline]
360    pub fn set_levels(self, levels: SEXP) -> Self {
361        self.0.set_levels(levels);
362        self
363    }
364    // endregion
365
366    // region: Convenience setters (string-based)
367
368    /// 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]
380    pub fn set_class_str(self, classes: &[&str]) -> Self {
381        use crate::SEXPTYPE::STRSXP;
382
383        let n: isize = classes
384            .len()
385            .try_into()
386            .expect("classes length exceeds isize::MAX");
387        unsafe {
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).
391            let _self_guard = OwnedProtect::new(self.0);
392            let class_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
393            for (i, class) in classes.iter().enumerate() {
394                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
395                class_vec.get().set_string_elt(idx, SEXP::charsxp(class));
396            }
397            self.0.set_class(class_vec.get());
398        }
399        self
400    }
401
402    /// Set class = `"data.frame"` using a cached class STRSXP.
403    ///
404    /// Equivalent to `set_class_str(&["data.frame"])` but avoids allocation.
405    #[inline]
406    pub fn set_data_frame_class(self) -> Self {
407        self.0
408            .set_class(crate::cached_class::data_frame_class_sexp());
409        self
410    }
411
412    /// 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]
424    pub fn set_names_str(self, names: &[&str]) -> Self {
425        use crate::SEXPTYPE::STRSXP;
426
427        let n: isize = names
428            .len()
429            .try_into()
430            .expect("names length exceeds isize::MAX");
431        unsafe {
432            // Protect self across the names-vector allocation; see set_class_str.
433            let _self_guard = OwnedProtect::new(self.0);
434            let names_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
435            for (i, name) in names.iter().enumerate() {
436                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
437                names_vec.get().set_string_elt(idx, SEXP::charsxp(name));
438            }
439            self.0.set_names(names_vec.get());
440        }
441        self
442    }
443
444    /// 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]
461    pub fn set_row_names_int(self, n: usize) -> Self {
462        unsafe {
463            // Protect self across the row.names allocation; see set_class_str.
464            let _self_guard = OwnedProtect::new(self.0);
465            // R's compact row.names: c(NA_integer_, -n)
466            let (row_names, rn) = crate::into_r::alloc_r_vector::<i32>(2);
467            let _guard = OwnedProtect::new(row_names);
468            rn[0] = i32::MIN; // NA_INTEGER
469            let 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            });
472            rn[1] = -n_i32;
473            self.0.set_row_names(row_names);
474        }
475        self
476    }
477
478    /// 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]
493    pub fn set_row_names_str(self, row_names: &[&str]) -> Self {
494        use crate::SEXPTYPE::STRSXP;
495
496        let n: isize = row_names
497            .len()
498            .try_into()
499            .expect("row_names length exceeds isize::MAX");
500        unsafe {
501            // Protect self across the row.names allocation; see set_class_str.
502            let _self_guard = OwnedProtect::new(self.0);
503            let names_vec = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
504            for (i, name) in row_names.iter().enumerate() {
505                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
506                names_vec.get().set_string_elt(idx, SEXP::charsxp(name));
507            }
508            self.0.set_row_names(names_vec.get());
509        }
510        self
511    }
512    // endregion
513
514    // region: Safe element insertion
515
516    /// 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]
544    pub unsafe fn set_elt(self, idx: isize, child: SEXP) {
545        if !(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
549        unsafe {
550            let _guard = OwnedProtect::new(child);
551            self.0.set_vector_elt(idx, child);
552        }
553    }
554
555    /// 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]
567    pub unsafe fn set_elt_unchecked(self, idx: isize, child: SEXP) {
568        if 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
570        self.0.set_vector_elt(idx, child);
571    }
572
573    /// 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]
597    pub unsafe fn set_elt_with<F>(self, idx: isize, f: F)
598    where
599        F: FnOnce() -> SEXP,
600    {
601        if !(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
603        unsafe {
604            let child = OwnedProtect::new(f());
605            self.0.set_vector_elt(idx, child.get());
606        }
607    }
608    // endregion
609}
610
611// region: ListBuilder - efficient batch list construction
612
613use crate::gc_protect::ProtectScope;
614
615/// 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}
641
642impl<'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]
651    pub unsafe fn new(scope: &'a ProtectScope, len: usize) -> Self {
652        // SAFETY: caller guarantees R main thread
653        let list = unsafe { scope.alloc_vecsxp(len).into_raw() };
654        Self {
655            list,
656            _scope: scope,
657        }
658    }
659
660    /// 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]
673    pub unsafe fn new_unchecked(scope: &'a ProtectScope, len: usize) -> Self {
674        // SAFETY: caller guarantees R main thread in a checked-bypass context.
675        let list = unsafe { scope.alloc_vecsxp_unchecked(len).into_raw() };
676        Self {
677            list,
678            _scope: scope,
679        }
680    }
681
682    /// 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]
689    pub unsafe fn from_protected(scope: &'a ProtectScope, list: SEXP) -> Self {
690        Self {
691            list,
692            _scope: scope,
693        }
694    }
695
696    /// 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]
706    pub unsafe fn set(&self, idx: isize, child: SEXP) {
707        // SAFETY: caller guarantees valid and protected child
708        if 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());
709        self.list.set_vector_elt(idx, child);
710    }
711
712    /// 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]
726    pub unsafe fn set_unchecked(&self, idx: isize, child: SEXP) {
727        // SAFETY: caller guarantees valid, protected child in a checked-bypass context.
728        if 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());
729        unsafe { self.list.set_vector_elt_unchecked(idx, child) };
730    }
731
732    /// 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]
740    pub unsafe fn set_protected(&self, idx: isize, child: SEXP) {
741        // SAFETY: caller guarantees valid child
742        unsafe {
743            if 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());
744            let _guard = OwnedProtect::new(child);
745            self.list.set_vector_elt(idx, child);
746        }
747    }
748
749    /// Get the underlying list SEXP.
750    #[inline]
751    pub fn as_sexp(&self) -> SEXP {
752        self.list
753    }
754
755    /// Convert to a `List` wrapper.
756    #[inline]
757    pub fn into_list(self) -> List {
758        List(self.list)
759    }
760
761    /// Convert to the underlying SEXP.
762    #[inline]
763    pub fn into_sexp(self) -> SEXP {
764        self.list
765    }
766
767    /// Get the length of the list.
768    #[inline]
769    pub fn len(&self) -> isize {
770        self.list.xlength()
771    }
772
773    /// Check if the list is empty.
774    #[inline]
775    pub fn is_empty(&self) -> bool {
776        self.len() == 0
777    }
778}
779// endregion
780
781mod accumulator;
782mod named;
783
784pub use accumulator::*;
785pub use named::*;
786
787// region: IntoList and TryFromList traits
788
789/// Convert things into an R list.
790pub trait IntoList {
791    /// Convert `self` into an R list wrapper.
792    fn into_list(self) -> List;
793}
794
795/// Fallible conversion from an R list into a Rust value.
796pub trait TryFromList: Sized {
797    /// Error returned when conversion fails.
798    type Error;
799
800    /// Attempt to convert an R list wrapper into `Self`.
801    fn try_from_list(list: List) -> Result<Self, Self::Error>;
802}
803
804// 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),+) => {
808        impl<$($T: IntoR),+> IntoList for ($($T,)+) {
809            fn into_list(self) -> List {
810                List(self.into_sexp())
811            }
812        }
813
814        impl<$($T: TryFromSexp),+> TryFromList for ($($T,)+)
815        where
816            $($T::Error: Into<SexpError>,)+
817        {
818            type Error = SexpError;
819
820            fn try_from_list(list: List) -> Result<Self, Self::Error> {
821                Self::try_from_sexp(list.0)
822            }
823        }
824    };
825}
826
827impl<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);
828
829impl<T: IntoR> IntoList for Vec<T> {
830    fn 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).
835        let n: isize = self
836            .len()
837            .try_into()
838            .expect("list length exceeds isize::MAX");
839        unsafe {
840            let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
841            for (i, val) in self.into_iter().enumerate() {
842                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
843                list.get().set_vector_elt(idx, val.into_sexp());
844            }
845            List(list.get())
846        }
847    }
848}
849
850impl<T> TryFromList for Vec<T>
851where
852    T: TryFromSexp<Error = SexpError>,
853{
854    type Error = SexpError;
855
856    fn try_from_list(list: List) -> Result<Self, Self::Error> {
857        let expected: usize = list
858            .len()
859            .try_into()
860            .expect("list length must be non-negative");
861        let mut out = Vec::with_capacity(expected);
862        for i in 0..expected {
863            let idx: isize = i.try_into().expect("index exceeds isize::MAX");
864            let 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        }
872        Ok(out)
873    }
874}
875
876// endregion
877
878// region: HashMap conversions
879
880impl<K, V> IntoList for HashMap<K, V>
881where
882    K: AsRef<str>,
883    V: IntoR,
884{
885    fn into_list(self) -> List {
886        let pairs: Vec<(K, V)> = self.into_iter().collect();
887        List::from_pairs(pairs)
888    }
889}
890
891/// 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> TryFromList for HashMap<String, V>
898where
899    V: TryFromSexp<Error = SexpError>,
900{
901    type Error = SexpError;
902
903    fn try_from_list(list: List) -> Result<Self, Self::Error> {
904        // A repeated name would leave only one of its values in the map.
905        if let Some(name) = list.first_duplicate_name() {
906            return Err(SexpError::DuplicateName(name));
907        }
908        let n: usize = list
909            .len()
910            .try_into()
911            .expect("list length must be non-negative");
912        let names_sexp = list.names();
913        let mut map = HashMap::with_capacity(n);
914
915        for i in 0..n {
916            let idx: isize = i.try_into().expect("index exceeds isize::MAX");
917            let sexp = list.get(idx).ok_or_else(|| {
918                SexpError::from(SexpLengthError {
919                    expected: n,
920                    actual: i,
921                })
922            })?;
923            let value: V = TryFromSexp::try_from_sexp(sexp)?;
924
925            let 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            };
930
931            map.insert(key, value);
932        }
933        Ok(map)
934    }
935}
936// endregion
937
938// region: BTreeMap conversions
939
940impl<K, V> IntoList for BTreeMap<K, V>
941where
942    K: AsRef<str>,
943    V: IntoR,
944{
945    fn into_list(self) -> List {
946        let pairs: Vec<(K, V)> = self.into_iter().collect();
947        List::from_pairs(pairs)
948    }
949}
950
951/// 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> TryFromList for BTreeMap<String, V>
958where
959    V: TryFromSexp<Error = SexpError>,
960{
961    type Error = SexpError;
962
963    fn try_from_list(list: List) -> Result<Self, Self::Error> {
964        // A repeated name would leave only one of its values in the map.
965        if let Some(name) = list.first_duplicate_name() {
966            return Err(SexpError::DuplicateName(name));
967        }
968        let n: usize = list
969            .len()
970            .try_into()
971            .expect("list length must be non-negative");
972        let names_sexp = list.names();
973        let mut map = BTreeMap::new();
974
975        for i in 0..n {
976            let idx: isize = i.try_into().expect("index exceeds isize::MAX");
977            let sexp = list.get(idx).ok_or_else(|| {
978                SexpError::from(SexpLengthError {
979                    expected: n,
980                    actual: i,
981                })
982            })?;
983            let value: V = TryFromSexp::try_from_sexp(sexp)?;
984
985            let 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            };
990
991            map.insert(key, value);
992        }
993        Ok(map)
994    }
995}
996// endregion
997
998// region: HashSet conversions (unnamed list <-> set)
999
1000impl<T> IntoList for HashSet<T>
1001where
1002    T: IntoR,
1003{
1004    fn into_list(self) -> List {
1005        let values: Vec<T> = self.into_iter().collect();
1006        values.into_list()
1007    }
1008}
1009
1010impl<T> TryFromList for HashSet<T>
1011where
1012    T: TryFromSexp<Error = SexpError> + Eq + Hash,
1013{
1014    type Error = SexpError;
1015
1016    fn try_from_list(list: List) -> Result<Self, Self::Error> {
1017        let vec: Vec<T> = TryFromList::try_from_list(list)?;
1018        Ok(vec.into_iter().collect())
1019    }
1020}
1021// endregion
1022
1023// region: BTreeSet conversions (unnamed list <-> set)
1024
1025impl<T> IntoList for BTreeSet<T>
1026where
1027    T: IntoR,
1028{
1029    fn into_list(self) -> List {
1030        let values: Vec<T> = self.into_iter().collect();
1031        values.into_list()
1032    }
1033}
1034
1035impl<T> TryFromList for BTreeSet<T>
1036where
1037    T: TryFromSexp<Error = SexpError> + Ord,
1038{
1039    type Error = SexpError;
1040
1041    fn try_from_list(list: List) -> Result<Self, Self::Error> {
1042        let vec: Vec<T> = TryFromList::try_from_list(list)?;
1043        Ok(vec.into_iter().collect())
1044    }
1045}
1046
1047impl List {
1048    /// Build a list from `(name, value)` pairs, setting `names` in one pass.
1049    pub fn from_pairs<N, T>(pairs: Vec<(N, T)>) -> Self
1050    where
1051        N: 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.
1058        let n: isize = pairs
1059            .len()
1060            .try_into()
1061            .expect("pairs length exceeds isize::MAX");
1062        unsafe {
1063            let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1064            let names = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
1065            for (i, (name, val)) in pairs.into_iter().enumerate() {
1066                let 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            }
1072            list.get().set_names(names.get());
1073            List(list.get())
1074        }
1075    }
1076
1077    /// 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    /// ```
1087    pub fn from_values<T: IntoR>(values: Vec<T>) -> Self {
1088        values.into_list()
1089    }
1090
1091    /// 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.
1097    pub fn from_raw_values(values: Vec<SEXP>) -> Self {
1098        let n: isize = values
1099            .len()
1100            .try_into()
1101            .expect("values length exceeds isize::MAX");
1102        unsafe {
1103            // Protect list during construction. SET_VECTOR_ELT doesn't allocate,
1104            // but we protect defensively in case this code is modified later.
1105            let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1106            for (i, val) in values.into_iter().enumerate() {
1107                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1108                list.get().set_vector_elt(idx, val);
1109            }
1110            List(list.get())
1111        }
1112    }
1113
1114    /// 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.
1127    pub fn from_scalars_or_list(elements: &[SEXP]) -> Self {
1128        use crate::SEXPTYPE;
1129        use crate::into_r::alloc_r_vector;
1130
1131        if elements.is_empty() {
1132            return Self::from_raw_values(Vec::new());
1133        }
1134
1135        let first_type = elements[0].type_of();
1136        let all_scalar_same_type = elements
1137            .iter()
1138            .all(|&e| e.xlength() == 1 && e.type_of() == first_type);
1139
1140        if !all_scalar_same_type {
1141            return Self::from_raw_values(elements.to_vec());
1142        }
1143
1144        let n = elements.len();
1145        let 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.
1148            SEXPTYPE::INTSXP => unsafe {
1149                let (v, dst) = alloc_r_vector::<i32>(n);
1150                for (slot, &elem) in dst.iter_mut().zip(elements.iter()) {
1151                    *slot = *elem.as_slice::<i32>().first().expect("scalar has length 1");
1152                }
1153                v
1154            },
1155            SEXPTYPE::REALSXP => unsafe {
1156                let (v, dst) = alloc_r_vector::<f64>(n);
1157                for (slot, &elem) in dst.iter_mut().zip(elements.iter()) {
1158                    *slot = *elem.as_slice::<f64>().first().expect("scalar has length 1");
1159                }
1160                v
1161            },
1162            SEXPTYPE::LGLSXP => unsafe {
1163                let (v, dst) = alloc_r_vector::<crate::RLogical>(n);
1164                for (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                }
1170                v
1171            },
1172            // STRSXP elements are CHARSXPs — must use SET_STRING_ELT (no slice access).
1173            SEXPTYPE::STRSXP => unsafe {
1174                let v = OwnedProtect::new(sys::Rf_allocVector(SEXPTYPE::STRSXP, n as isize));
1175                for (i, &elem) in elements.iter().enumerate() {
1176                    let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1177                    v.get().set_string_elt(idx, elem.string_elt(0));
1178                }
1179                v.get()
1180            },
1181            _ => return Self::from_raw_values(elements.to_vec()),
1182        };
1183        List(sexp)
1184    }
1185
1186    /// 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.
1193    pub fn from_raw_pairs<N>(pairs: Vec<(N, SEXP)>) -> Self
1194    where
1195        N: AsRef<str>,
1196    {
1197        let n: isize = pairs
1198            .len()
1199            .try_into()
1200            .expect("pairs length exceeds isize::MAX");
1201        unsafe {
1202            // CRITICAL: Both list and names must be protected because
1203            // Rf_mkCharLenCE can allocate and trigger GC in the loop below.
1204            let list = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1205            let names = OwnedProtect::new(sys::Rf_allocVector(STRSXP, n));
1206            for (i, (name, val)) in pairs.into_iter().enumerate() {
1207                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1208                list.get().set_vector_elt(idx, val);
1209
1210                let s = name.as_ref();
1211                // SEXP::charsxp allocates - list and names must be protected!
1212                names.get().set_string_elt(idx, SEXP::charsxp(s));
1213            }
1214            list.get().set_names(names.get());
1215            List(list.get())
1216        }
1217    }
1218
1219    /// 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]
1230    pub fn from_raw_pairs_empty() -> Self {
1231        Self::from_raw_pairs(Vec::<(&str, SEXP)>::new())
1232    }
1233}
1234
1235impl IntoR for List {
1236    type Error = std::convert::Infallible;
1237    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1238        Ok(self.into_sexp())
1239    }
1240    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1241        self.try_into_sexp()
1242    }
1243    #[inline]
1244    fn into_sexp(self) -> SEXP {
1245        self.0
1246    }
1247}
1248
1249impl IntoR for ListMut {
1250    type Error = std::convert::Infallible;
1251    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1252        Ok(self.into_sexp())
1253    }
1254    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1255        self.try_into_sexp()
1256    }
1257    #[inline]
1258    fn into_sexp(self) -> SEXP {
1259        self.0
1260    }
1261}
1262
1263/// `Some(list)` → the list, `None` → `NULL`: the inverse of
1264/// `TryFromSexp for Option<List>`.
1265impl IntoR for Option<List> {
1266    type Error = std::convert::Infallible;
1267    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1268        Ok(self.into_sexp())
1269    }
1270    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1271        self.try_into_sexp()
1272    }
1273    #[inline]
1274    fn into_sexp(self) -> SEXP {
1275        self.map_or_else(SEXP::nil, |list| list.0)
1276    }
1277}
1278
1279/// `Some(list)` → the list, `None` → `NULL`: the inverse of
1280/// `TryFromSexp for Option<ListMut>`.
1281impl IntoR for Option<ListMut> {
1282    type Error = std::convert::Infallible;
1283    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1284        Ok(self.into_sexp())
1285    }
1286    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1287        self.try_into_sexp()
1288    }
1289    #[inline]
1290    fn into_sexp(self) -> SEXP {
1291        self.map_or_else(SEXP::nil, |list| list.0)
1292    }
1293}
1294
1295/// 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 {
1307    let n: isize = values
1308        .len()
1309        .try_into()
1310        .expect("list-column length exceeds isize::MAX");
1311    unsafe {
1312        let out = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1313        for (i, value) in values.into_iter().enumerate() {
1314            let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1315            // No allocation between building the list and storing it.
1316            out.get().set_vector_elt(idx, value.into_list().0);
1317        }
1318        out.get()
1319    }
1320}
1321
1322/// [`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 {
1325    let n: isize = values
1326        .len()
1327        .try_into()
1328        .expect("list-column length exceeds isize::MAX");
1329    unsafe {
1330        // VECSXP slots start as R_NilValue, so `None` cells need no write.
1331        let out = OwnedProtect::new(sys::Rf_allocVector(VECSXP, n));
1332        for (i, value) in values.into_iter().enumerate() {
1333            if let Some(value) = value {
1334                let idx: isize = i.try_into().expect("index exceeds isize::MAX");
1335                out.get().set_vector_elt(idx, value.into_list().0);
1336            }
1337        }
1338        out.get()
1339    }
1340}
1341
1342/// 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 IntoR for Vec<List> {
1349    type Error = std::convert::Infallible;
1350    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1351        Ok(self.into_sexp())
1352    }
1353    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1354        self.try_into_sexp()
1355    }
1356    fn into_sexp(self) -> SEXP {
1357        unsafe {
1358            use crate::gc_protect::OwnedProtect;
1359            use crate::sys::Rf_allocVector;
1360            use crate::{SEXPTYPE, SexpExt as _};
1361            let 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).
1365            let out = OwnedProtect::new(Rf_allocVector(SEXPTYPE::VECSXP, n));
1366            for (i, list) in self.into_iter().enumerate() {
1367                out.get().set_vector_elt(i as crate::R_xlen_t, list.0);
1368            }
1369            *out
1370        }
1371    }
1372}
1373
1374/// 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 IntoR for Vec<Option<List>> {
1380    type Error = std::convert::Infallible;
1381    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1382        Ok(self.into_sexp())
1383    }
1384    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1385        self.try_into_sexp()
1386    }
1387    fn into_sexp(self) -> SEXP {
1388        unsafe {
1389            use crate::gc_protect::OwnedProtect;
1390            use crate::sys::Rf_allocVector;
1391            use crate::{SEXPTYPE, SexpExt as _};
1392            let 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.
1396            let out = OwnedProtect::new(Rf_allocVector(SEXPTYPE::VECSXP, n));
1397            for (i, opt) in self.into_iter().enumerate() {
1398                if let Some(list) = opt {
1399                    out.get().set_vector_elt(i as crate::R_xlen_t, list.0);
1400                }
1401            }
1402            *out
1403        }
1404    }
1405}
1406
1407/// 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 TryFromSexp for List {
1420    type Error = SexpTypeError;
1421
1422    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1423        let actual = sexp.type_of();
1424        if actual == VECSXP {
1425            Ok(List(sexp))
1426        } else {
1427            Err(SexpTypeError {
1428                expected: VECSXP,
1429                actual,
1430            })
1431        }
1432    }
1433}
1434
1435impl TryFromSexp for Option<List> {
1436    type Error = SexpError;
1437
1438    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1439        if sexp == SEXP::nil() {
1440            return Ok(None);
1441        }
1442        Ok(Some(List::try_from_sexp(sexp)?))
1443    }
1444}
1445
1446/// 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> {
1450    let actual = elem.type_of();
1451    if actual == VECSXP {
1452        Ok(List(elem))
1453    } else {
1454        Err(SexpTypeError {
1455            expected: VECSXP,
1456            actual,
1457        }
1458        .into())
1459    }
1460}
1461
1462/// 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 TryFromSexp for Vec<List> {
1475    type Error = SexpError;
1476
1477    #[inline]
1478    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1479        Self::__mx_try_from_sexp_with_check(sexp, &no_element_check)
1480    }
1481
1482    #[inline]
1483    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
1484        Self::try_from_sexp(sexp)
1485    }
1486
1487    /// `check` runs on each element, before the element is read.
1488    fn __mx_try_from_sexp_with_check(
1489        sexp: SEXP,
1490        check: &ElementCheck<'_>,
1491    ) -> Result<Self, SexpError> {
1492        map_vecsxp_batched(sexp, |elem| {
1493            check(elem)?;
1494            list_element(elem)
1495        })
1496    }
1497
1498    #[inline]
1499    unsafe fn __mx_try_from_sexp_unchecked_with_check(
1500        sexp: SEXP,
1501        check: &ElementCheck<'_>,
1502    ) -> Result<Self, SexpError> {
1503        Self::__mx_try_from_sexp_with_check(sexp, check)
1504    }
1505}
1506
1507/// 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 TryFromSexp for Vec<Option<List>> {
1514    type Error = SexpError;
1515
1516    #[inline]
1517    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1518        Self::__mx_try_from_sexp_with_check(sexp, &no_element_check)
1519    }
1520
1521    #[inline]
1522    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
1523        Self::try_from_sexp(sexp)
1524    }
1525
1526    /// `check` runs on each element but `NULL`, before the element is read.
1527    fn __mx_try_from_sexp_with_check(
1528        sexp: SEXP,
1529        check: &ElementCheck<'_>,
1530    ) -> Result<Self, SexpError> {
1531        map_vecsxp_batched(sexp, |elem| {
1532            if elem.type_of() == NILSXP {
1533                return Ok(None);
1534            }
1535            check(elem)?;
1536            list_element(elem).map(Some)
1537        })
1538    }
1539
1540    #[inline]
1541    unsafe fn __mx_try_from_sexp_unchecked_with_check(
1542        sexp: SEXP,
1543        check: &ElementCheck<'_>,
1544    ) -> Result<Self, SexpError> {
1545        Self::__mx_try_from_sexp_with_check(sexp, check)
1546    }
1547}
1548
1549impl TryFromSexp for Option<ListMut> {
1550    type Error = SexpError;
1551
1552    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1553        if sexp == SEXP::nil() {
1554            return Ok(None);
1555        }
1556        let list = ListMut::try_from_sexp(sexp)?;
1557        Ok(Some(list))
1558    }
1559}
1560
1561impl TryFromSexp for ListMut {
1562    type Error = SexpError;
1563
1564    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1565        let actual = sexp.type_of();
1566        if actual != VECSXP {
1567            return Err(SexpTypeError {
1568                expected: VECSXP,
1569                actual,
1570            }
1571            .into());
1572        }
1573        Ok(ListMut(sexp))
1574    }
1575}
1576// endregion