Skip to main content

miniextendr_api/list/
named.rs

1//! `NamedList` — O(1) name-indexed access to R lists.
2//!
3//! Wraps a [`List`] and builds a `HashMap<String, usize>` index
4//! on construction. Use when accessing multiple elements by name from the
5//! same list — each lookup is O(1) instead of O(n).
6
7use std::collections::HashMap;
8
9use crate::from_r::{SexpError, TryFromSexp};
10use crate::into_r::IntoR;
11use crate::{SEXP, SexpExt};
12
13use super::List;
14
15/// A named list with O(1) name-based element lookup.
16///
17/// Wraps a [`List`] and builds a `HashMap<String, usize>` index of element names
18/// on construction. Use this when you need to access multiple elements by name
19/// from the same list — each lookup is O(1) instead of O(n).
20///
21/// # When to Use
22///
23/// | Pattern | Type |
24/// |---------|------|
25/// | Single named lookup | [`List::get_named`] is fine |
26/// | Multiple named lookups | `NamedList` (O(n) build + O(1) per lookup) |
27/// | Positional access only | [`List`] — no indexing overhead |
28///
29/// # Name Handling
30///
31/// - A Latin-1 name is indexed by its UTF-8 translation; `NA`, empty-string
32///   and non-text names (marked as bytes, or not valid UTF-8) are excluded
33///   from the index
34/// - If a name appears more than once, the **first** occurrence wins, as with
35///   R's `x[["name"]]` and [`List::get_named`]; check
36///   [`List::first_duplicate_name`] to refuse such a list instead
37/// - Positional access via [`get_index`](Self::get_index) is always available
38pub struct NamedList {
39    list: List,
40    index: HashMap<String, usize>,
41}
42
43impl NamedList {
44    /// Build a `NamedList` from a `List`, indexing all non-empty, non-NA names.
45    /// A repeated name indexes its first element.
46    ///
47    /// Returns `None` if the list has no `names` attribute.
48    pub fn new(list: List) -> Option<Self> {
49        // No `names` attribute, no `NamedList`.
50        list.names()?;
51        let n: usize = list
52            .len()
53            .try_into()
54            .expect("list length must be non-negative");
55        let mut index = HashMap::with_capacity(n);
56
57        for (i, s) in list.text_names() {
58            if !s.is_empty() && !index.contains_key(s) {
59                let i: usize = i.try_into().expect("list position is non-negative");
60                index.insert(s.to_owned(), i);
61            }
62        }
63
64        Some(NamedList { list, index })
65    }
66
67    /// Get an element by name with O(1) lookup, converting to type `T`.
68    ///
69    /// Returns `None` if the name is not found or conversion fails. The
70    /// conversion error is discarded, so `T`'s `TryFromSexp::Error` is
71    /// unconstrained; use [`get_raw`](Self::get_raw) when you need the error.
72    #[inline]
73    pub fn get<T>(&self, name: &str) -> Option<T>
74    where
75        T: TryFromSexp,
76    {
77        let &idx = self.index.get(name)?;
78        let idx_isize: isize = idx.try_into().ok()?;
79        let elem = self.list.as_sexp().vector_elt(idx_isize);
80        T::try_from_sexp(elem).ok()
81    }
82
83    /// Get a raw SEXP element by name with O(1) lookup.
84    #[inline]
85    pub fn get_raw(&self, name: &str) -> Option<SEXP> {
86        let &idx = self.index.get(name)?;
87        let idx_isize: isize = idx.try_into().ok()?;
88        Some(self.list.as_sexp().vector_elt(idx_isize))
89    }
90
91    /// Get element at 0-based index and convert to type `T`.
92    ///
93    /// Falls through to [`List::get_index`] — no name lookup involved.
94    #[inline]
95    pub fn get_index<T>(&self, idx: isize) -> Option<T>
96    where
97        T: TryFromSexp,
98    {
99        self.list.get_index(idx)
100    }
101
102    /// Check if a name exists in the index.
103    #[inline]
104    pub fn contains(&self, name: &str) -> bool {
105        self.index.contains_key(name)
106    }
107
108    /// Number of elements in the list (including unnamed ones).
109    #[inline]
110    pub fn len(&self) -> isize {
111        self.list.len()
112    }
113
114    /// Returns `true` if the list is empty.
115    #[inline]
116    pub fn is_empty(&self) -> bool {
117        self.list.is_empty()
118    }
119
120    /// Number of indexed (named) elements.
121    #[inline]
122    pub fn named_len(&self) -> usize {
123        self.index.len()
124    }
125
126    /// Get the underlying `List`.
127    #[inline]
128    pub fn as_list(&self) -> List {
129        self.list
130    }
131
132    /// Consume and return the underlying `List`.
133    #[inline]
134    pub fn into_list(self) -> List {
135        self.list
136    }
137
138    /// Iterate over indexed names (unordered).
139    pub fn names(&self) -> impl Iterator<Item = &str> {
140        self.index.keys().map(|s| s.as_str())
141    }
142
143    /// Iterate over `(name, position)` pairs (unordered).
144    pub fn entries(&self) -> impl Iterator<Item = (&str, usize)> {
145        self.index.iter().map(|(k, &v)| (k.as_str(), v))
146    }
147}
148
149impl IntoR for NamedList {
150    type Error = std::convert::Infallible;
151    fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
152        Ok(self.into_sexp())
153    }
154    unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
155        self.try_into_sexp()
156    }
157    #[inline]
158    fn into_sexp(self) -> SEXP {
159        self.list.into_sexp()
160    }
161}
162
163impl TryFromSexp for NamedList {
164    type Error = SexpError;
165
166    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
167        let list = List::try_from_sexp(sexp)?;
168        NamedList::new(list)
169            .ok_or_else(|| SexpError::InvalidValue("list has no names attribute".into()))
170    }
171}
172
173impl TryFromSexp for Option<NamedList> {
174    type Error = SexpError;
175
176    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
177        if sexp == SEXP::nil() {
178            return Ok(None);
179        }
180        let named = NamedList::try_from_sexp(sexp)?;
181        Ok(Some(named))
182    }
183}
184
185// IntoList and TryFromList traits are defined in the parent list.rs module.