Skip to main content

miniextendr_api/
factor.rs

1//! Factor support for enum ↔ R factor conversions.
2//!
3//! R factors are integer vectors with a `levels` attribute (character vector)
4//! and a `class` attribute set to `"factor"`. The integer payload uses 1-based
5//! indexing into the levels, with `NA_INTEGER` for missing values.
6//!
7//! # Usage
8//!
9//! ```ignore
10//! use miniextendr_api::RFactor;
11//!
12//! #[derive(Copy, Clone, RFactor)]
13//! enum Color { Red, Green, Blue }
14//!
15//! // Enum values convert to/from R factors automatically
16//! #[miniextendr]
17//! fn describe(c: Color) -> &'static str {
18//!     match c {
19//!         Color::Red => "red",
20//!         Color::Green => "green",
21//!         Color::Blue => "blue",
22//!     }
23//! }
24//! ```
25
26use std::ops::Deref;
27use std::sync::OnceLock;
28
29use crate::altrep_traits::NA_INTEGER;
30use crate::from_r::{
31    BatchedErrors, SexpError, SexpLengthError, SexpNaError, TryFromSexp, charsxp_to_cow_lossy,
32};
33use crate::gc_protect::OwnedProtect;
34use crate::into_r::IntoR;
35use crate::sys::Rf_allocVector;
36use crate::{IsNA, SEXP, SEXPTYPE, SexpExt};
37
38// region: Cached "factor" class STRSXP
39
40static FACTOR_CLASS: OnceLock<SEXP> = OnceLock::new();
41
42pub(crate) fn factor_class_sexp() -> SEXP {
43    *FACTOR_CLASS.get_or_init(|| build_levels_sexp_cached(&["factor"]))
44}
45// endregion
46
47// region: RFactor trait
48
49/// Trait for mapping Rust enums to R factors.
50///
51/// Typically implemented via `#[derive(RFactor)]` for C-style enums.
52/// The derive macro also generates `IntoR` and `TryFromSexp` implementations.
53pub trait RFactor: crate::match_arg::MatchArg + Copy + 'static {
54    /// Convert variant to 1-based level index.
55    fn to_level_index(self) -> i32;
56
57    /// Convert 1-based level index to variant, or `None` if out of range.
58    fn from_level_index(idx: i32) -> Option<Self>;
59}
60// endregion
61
62// region: Core building functions
63
64/// Build a levels STRSXP of UTF-8 CHARSXPs.
65///
66/// Level names are not interned as R symbols, so names built from data stay
67/// collectable. The returned STRSXP is NOT protected - caller must protect or
68/// preserve it.
69///
70/// # Panics
71///
72/// If a level name contains a null byte.
73pub fn build_levels_sexp(levels: &[&str]) -> SEXP {
74    build_levels_sexp_protected(levels).get()
75}
76
77/// Keep the container rooted while each level's CHARSXP is allocated.
78fn build_levels_sexp_protected(levels: &[&str]) -> OwnedProtect {
79    // `Rf_mkCharLenCE` raises an R error on an embedded nul, which would
80    // longjmp over the container's protection.
81    if levels.iter().any(|level| level.as_bytes().contains(&0)) {
82        {
    ::core::panicking::panic_fmt(format_args!("level name contains null byte"));
};panic!("level name contains null byte");
83    }
84    let len = levels.len().try_into().expect("too many factor levels");
85    unsafe {
86        let sexp = OwnedProtect::new(Rf_allocVector(SEXPTYPE::STRSXP, len));
87        for (i, level) in (0..len).zip(levels) {
88            // A new CHARSXP is unrooted until it is stored in the protected
89            // container. R's CHARSXP cache shares repeated names.
90            sexp.set_string_elt(i, SEXP::charsxp(level));
91        }
92        sexp
93    }
94}
95
96/// Build a levels STRSXP and preserve it permanently (for caching).
97pub fn build_levels_sexp_cached(levels: &[&str]) -> SEXP {
98    unsafe {
99        let sexp = build_levels_sexp_protected(levels);
100        crate::sys::R_PreserveObject(sexp.get());
101        sexp.get()
102    }
103}
104
105/// Build a factor SEXP from indices and a levels STRSXP.
106///
107/// The caller must keep `levels` rooted across this call. The factor is rooted
108/// during construction; the returned SEXP must be protected or returned to R.
109pub fn build_factor(indices: &[i32], levels: SEXP) -> SEXP {
110    unsafe {
111        let (sexp, dst) = crate::into_r::alloc_r_vector::<i32>(indices.len());
112        // Attribute assignment and the cold class-cache initializer allocate.
113        let sexp = OwnedProtect::new(sexp);
114        dst.copy_from_slice(indices);
115        sexp.set_levels(levels);
116        sexp.set_class(factor_class_sexp());
117        sexp.get()
118    }
119}
120
121/// Build a factor SEXP from indices and level names in a single call.
122///
123/// Keeps the levels STRSXP rooted from allocation through [`build_factor`],
124/// so callers don't need to manage
125/// the levels protection themselves. The returned factor SEXP is **not**
126/// protected — caller must protect or return it.
127///
128/// This is the recommended path for one-shot factor construction; for
129/// repeated calls with the same levels prefer caching via
130/// [`build_levels_sexp_cached`] (no protection needed because the cached
131/// SEXP is on R's precious list).
132///
133/// The levels container roots its strings; the container and the factor
134/// payload are rooted while being built.
135pub fn build_factor_with_levels(indices: &[i32], level_names: &[&str]) -> SEXP {
136    let levels = build_levels_sexp_protected(level_names);
137    build_factor(indices, levels.get())
138}
139// endregion
140
141// region: Validation helper
142
143/// Validate that a factor has the expected levels.
144pub(crate) fn validate_factor_levels(sexp: SEXP, expected: &[&str]) -> Result<(), SexpError> {
145    if !sexp.is_factor() {
146        return Err(SexpError::InvalidValue("expected a factor".into()));
147    }
148
149    let levels = sexp.get_levels();
150    if levels.type_of() != SEXPTYPE::STRSXP {
151        return Err(SexpError::InvalidValue("levels is not STRSXP".into()));
152    }
153
154    let n = levels.len();
155    if n != expected.len() {
156        return Err(SexpError::InvalidValue(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("expected {0} levels, got {1}",
                expected.len(), n))
    })format!(
157            "expected {} levels, got {}",
158            expected.len(),
159            n
160        )));
161    }
162
163    for (i, exp) in expected.iter().enumerate() {
164        let charsxp = levels.string_elt(i as isize);
165        let actual = unsafe { charsxp_to_cow_lossy(charsxp) };
166        if actual != *exp {
167            return Err(SexpError::InvalidValue(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("level {0}: expected \'{1}\', got \'{2}\'",
                i + 1, exp, actual))
    })format!(
168                "level {}: expected '{}', got '{}'",
169                i + 1,
170                exp,
171                actual
172            )));
173        }
174    }
175
176    Ok(())
177}
178// endregion
179
180// region: Conversion helpers (used by derive macro)
181
182/// The reason a factor code does not name one of the levels (a malformed
183/// factor: [`validate_factor_levels`] has already checked the level set).
184fn code_not_a_level(code: i32) -> String {
185    ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("code {0} is not a level of the factor",
                code))
    })format!("code {code} is not a level of the factor")
186}
187
188/// Read every code of a factor through `elt`, batching every failing element
189/// (its reason and 1-based position) into one error instead of stopping at
190/// the first.
191fn read_factor_codes<U>(
192    sexp: SEXP,
193    elt: impl Fn(i32) -> Result<U, String>,
194) -> Result<Vec<U>, SexpError> {
195    let len = sexp.len();
196    let mut result = Vec::with_capacity(len);
197    let mut errors = BatchedErrors::default();
198    for i in 0..len {
199        match elt(sexp.integer_elt(i as isize)) {
200            Ok(v) => result.push(v),
201            Err(reason) => errors.push(i, || reason),
202        }
203    }
204    if errors.is_empty() {
205        Ok(result)
206    } else {
207        Err(errors.into_element_error())
208    }
209}
210
211/// Convert an R factor SEXP to a single enum value.
212#[inline]
213pub fn factor_from_sexp<T: RFactor>(sexp: SEXP) -> Result<T, SexpError> {
214    validate_factor_levels(sexp, T::CHOICES)?;
215
216    let len = sexp.len();
217    if len != 1 {
218        return Err(SexpLengthError {
219            expected: 1,
220            actual: len,
221        }
222        .into());
223    }
224
225    let idx = sexp.integer_elt(0);
226    if idx.is_na() {
227        return Err(SexpNaError {
228            sexp_type: SEXPTYPE::INTSXP,
229        }
230        .into());
231    }
232
233    T::from_level_index(idx).ok_or_else(|| SexpError::InvalidValue(code_not_a_level(idx)))
234}
235
236/// Convert an R factor SEXP to a Vec of enum values. Every `NA` and every
237/// code outside the levels is reported, with its position.
238#[inline]
239pub(crate) fn factor_vec_from_sexp<T: UnitEnumFactor>(sexp: SEXP) -> Result<Vec<T>, SexpError> {
240    validate_factor_levels(sexp, T::FACTOR_LEVELS)?;
241    read_factor_codes(sexp, |idx| {
242        if idx.is_na() {
243            return Err("NA is not allowed".to_string());
244        }
245        T::from_factor_index(idx).ok_or_else(|| code_not_a_level(idx))
246    })
247}
248
249/// Convert an R factor SEXP to a Vec of Option enum values (NA → None).
250#[inline]
251pub(crate) fn factor_option_vec_from_sexp<T: RFactor>(
252    sexp: SEXP,
253) -> Result<Vec<Option<T>>, SexpError> {
254    validate_factor_levels(sexp, T::CHOICES)?;
255    read_factor_codes(sexp, |idx| {
256        if idx.is_na() {
257            return Ok(None);
258        }
259        T::from_level_index(idx)
260            .map(Some)
261            .ok_or_else(|| code_not_a_level(idx))
262    })
263}
264
265/// Convert an R factor SEXP to a `Vec<Option<T>>` using [`UnitEnumFactor`] (NA → `None`).
266///
267/// Used by the enum DataFrame reader to reconstruct `as_factor` columns.
268/// Unlike `factor_option_vec_from_sexp` (which requires `RFactor + MatchArg`),
269/// this accepts any `UnitEnumFactor` — including `#[derive(DataFrameRow)]`
270/// unit-only enums that do not implement `RFactor`.
271#[inline]
272pub fn unit_factor_option_vec_from_sexp<T: UnitEnumFactor>(
273    sexp: SEXP,
274) -> Result<Vec<Option<T>>, SexpError> {
275    validate_factor_levels(sexp, T::FACTOR_LEVELS)?;
276    read_factor_codes(sexp, |idx| {
277        if idx.is_na() {
278            return Ok(None);
279        }
280        T::from_factor_index(idx)
281            .map(Some)
282            .ok_or_else(|| code_not_a_level(idx))
283    })
284}
285// endregion
286
287// region: Newtype wrappers (for orphan rule workaround)
288
289/// Wrapper for `Vec<T: UnitEnumFactor>` enabling `IntoR`/`TryFromSexp`.
290///
291/// Accepts both `RFactor` types and unit-only `DataFrameRow` enums. Values are
292/// moved during conversion; neither `Copy` nor `Clone` is required.
293#[derive(#[automatically_derived]impl<T: ::core::fmt::Debug> ::core::fmt::Debug for
    FactorVec<T> {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field1_finish(f, "FactorVec",
            &&self.0)
    }
}Debug, #[automatically_derived]impl<T: ::core::clone::Clone> ::core::clone::Clone for
    FactorVec<T> {
    #[inline]
    fn clone(&self) -> Self {
        FactorVec(::core::clone::Clone::clone(&self.0))
    }
}Clone)]
294pub struct FactorVec<T>(pub Vec<T>);
295
296impl<T> FactorVec<T> {
297    /// Wrap a `Vec<T>` so it can be converted to and from R factors.
298    pub fn new(vec: Vec<T>) -> Self {
299        Self(vec)
300    }
301
302    /// Extract the inner vector.
303    pub fn into_inner(self) -> Vec<T> {
304        self.0
305    }
306}
307
308impl<T> From<Vec<T>> for FactorVec<T> {
309    fn from(vec: Vec<T>) -> Self {
310        Self(vec)
311    }
312}
313
314impl<T> Deref for FactorVec<T> {
315    type Target = Vec<T>;
316    fn deref(&self) -> &Self::Target {
317        &self.0
318    }
319}
320
321impl<T> std::ops::DerefMut for FactorVec<T> {
322    fn deref_mut(&mut self) -> &mut Self::Target {
323        &mut self.0
324    }
325}
326
327impl<T: UnitEnumFactor> IntoR for FactorVec<T> {
328    type Error = std::convert::Infallible;
329    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
330        Ok(self.into_sexp())
331    }
332    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
333        self.try_into_sexp()
334    }
335    fn into_sexp(self) -> SEXP {
336        let indices: Vec<i32> = self.0.into_iter().map(T::to_factor_index).collect();
337        // build_factor_with_levels protects the levels STRSXP across the
338        // build_factor allocation — see "PROTECT discipline against R-devel GC".
339        build_factor_with_levels(&indices, T::FACTOR_LEVELS)
340    }
341}
342
343impl<T: UnitEnumFactor> TryFromSexp for FactorVec<T> {
344    type Error = SexpError;
345    const CHARACTER_ONLY: bool = true;
346    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
347        factor_vec_from_sexp(sexp).map(FactorVec)
348    }
349}
350
351/// Wrapper for `Vec<Option<T: RFactor>>` with NA support.
352#[derive(#[automatically_derived]impl<T: ::core::fmt::Debug> ::core::fmt::Debug for
    FactorOptionVec<T> {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field1_finish(f,
            "FactorOptionVec", &&self.0)
    }
}Debug, #[automatically_derived]impl<T: ::core::clone::Clone> ::core::clone::Clone for
    FactorOptionVec<T> {
    #[inline]
    fn clone(&self) -> Self {
        FactorOptionVec(::core::clone::Clone::clone(&self.0))
    }
}Clone)]
353pub struct FactorOptionVec<T>(pub Vec<Option<T>>);
354
355impl<T> FactorOptionVec<T> {
356    /// Wrap a `Vec<Option<T>>` so it can be converted to and from R factors with NA support.
357    pub fn new(vec: Vec<Option<T>>) -> Self {
358        Self(vec)
359    }
360
361    /// Extract the inner vector.
362    pub fn into_inner(self) -> Vec<Option<T>> {
363        self.0
364    }
365}
366
367impl<T> From<Vec<Option<T>>> for FactorOptionVec<T> {
368    fn from(vec: Vec<Option<T>>) -> Self {
369        Self(vec)
370    }
371}
372
373impl<T> Deref for FactorOptionVec<T> {
374    type Target = Vec<Option<T>>;
375    fn deref(&self) -> &Self::Target {
376        &self.0
377    }
378}
379
380impl<T> std::ops::DerefMut for FactorOptionVec<T> {
381    fn deref_mut(&mut self) -> &mut Self::Target {
382        &mut self.0
383    }
384}
385
386// Blanket: every RFactor type is also a UnitEnumFactor (provides IntoR for FactorOptionVec<T>).
387impl<T: RFactor + crate::match_arg::MatchArg> UnitEnumFactor for T {
388    const FACTOR_LEVELS: &'static [&'static str] = T::CHOICES;
389    fn to_factor_index(self) -> i32 {
390        self.to_level_index()
391    }
392    fn from_factor_index(idx: i32) -> Option<Self> {
393        T::from_level_index(idx)
394    }
395}
396
397impl<T: RFactor> TryFromSexp for FactorOptionVec<T> {
398    type Error = SexpError;
399    const CHARACTER_ONLY: bool = true;
400    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
401        factor_option_vec_from_sexp(sexp).map(FactorOptionVec)
402    }
403}
404
405// region: UnitEnumFactor — factor trait for DataFrameRow unit-only enums
406
407/// Trait implemented by unit-only enums derived via `#[derive(DataFrameRow)]`.
408///
409/// Provides the level names and 1-based index needed to convert enum values
410/// into R factor SEXPs. Unlike `RFactor`, this trait does **not** require
411/// `Copy` or `MatchArg`, making it usable with `DataFrameRow`-derived types
412/// that only need to participate as factor columns in data frames.
413///
414/// Implemented automatically by `#[derive(DataFrameRow)]` on unit-only enums.
415/// `FactorVec<T>` and `FactorOptionVec<T>` provide the SEXP conversion used by the
416/// companion struct's `into_data_frame` method.
417///
418/// # Safety contract
419///
420/// `to_factor_index` must return a value in `1..=FACTOR_LEVELS.len() as i32`
421/// (or `NA_INTEGER` for missing) to produce a valid R factor SEXP.
422pub trait UnitEnumFactor: Sized {
423    /// Ordered level names (in the same order as the enum variants).
424    const FACTOR_LEVELS: &'static [&'static str];
425
426    /// Convert `self` to a 1-based R factor level index.
427    fn to_factor_index(self) -> i32;
428
429    /// Inverse: 1-based level index → variant, or `None` if out of range.
430    ///
431    /// Used by the enum DataFrame reader to reconstruct unit-only enum values
432    /// from an R factor column. The default blanket impl delegates to the
433    /// underlying `RFactor::from_level_index`.
434    fn from_factor_index(idx: i32) -> Option<Self>;
435}
436
437impl<T: UnitEnumFactor> IntoR for FactorOptionVec<T> {
438    type Error = std::convert::Infallible;
439    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
440        Ok(self.into_sexp())
441    }
442    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
443        self.try_into_sexp()
444    }
445    fn into_sexp(self) -> SEXP {
446        // Generic statics aren't allowed in Rust, so levels are built per call.
447        // build_factor_with_levels protects the levels STRSXP across the
448        // build_factor allocation — see "PROTECT discipline against R-devel GC".
449        let indices: Vec<i32> = self
450            .0
451            .into_iter()
452            .map(|opt| match opt {
453                None => NA_INTEGER,
454                Some(v) => v.to_factor_index(),
455            })
456            .collect();
457        build_factor_with_levels(&indices, T::FACTOR_LEVELS)
458    }
459}
460// endregion: UnitEnumFactor
461
462// region: Tests
463
464#[cfg(test)]
465mod tests;
466// endregion