Skip to main content

miniextendr_api/dataframe/
group.rs

1//! Group-level iteration over a [`DataFrame`] key column.
2//!
3//! Two rungs, cheapest first:
4//!
5//! 1. **Typed rows, grouped Rust-side** — after `Vec::<Row>::from_dataframe(&df)?`,
6//!    grouping is plain Rust. [`group_rows`] makes the idiom discoverable:
7//!
8//!    ```ignore
9//!    let rows: Vec<Obs> = Vec::from_dataframe(&df)?;
10//!    let by_site = group_rows(rows, |r| r.site.clone());
11//!    // by_site: BTreeMap<String, Vec<Obs>> — plain Rust data, rayon-safe.
12//!    ```
13//!
14//! 2. **Untyped, index-based** — [`DataFrame::group_by`] computes group indices
15//!    once (single pass, main thread) without extracting rows:
16//!
17//!    ```ignore
18//!    let grouped = df.group_by("site")?;
19//!    for (key, rows) in grouped.iter() { /* key: &GroupKey, rows: &[usize] */ }
20//!    let mut out = NamedListBuilder::with_capacity(grouped.len());
21//!    for (key, sub) in grouped.frames() {
22//!        // Transfer each rooted frame into the owned list.
23//!        out.push(key.label(), sub);
24//!    }
25//!    ```
26//!
27//! # Key semantics (vs R `split()`)
28//!
29//! - **Group order**: factor keys follow level order (empty levels kept, like
30//!   `split()`); character keys sort in byte order (R sorts in locale collation
31//!   order — identical for ASCII); integer keys sort numerically; logical keys
32//!   order `FALSE`, `TRUE`; double keys (`Date` and `POSIXct` included) sort
33//!   numerically, with `NaN` after every number.
34//! - **`NA` keys form one group, ordered last** — a deliberate deviation from
35//!   `split()`, which silently drops NA-keyed rows. A literal NA *level*
36//!   (`addNA(f)`) also surfaces as [`GroupKey::Na`].
37//! - **Double keys group by value with dplyr's (vctrs') equality**: `-0` and
38//!   `0` are one key, every `NaN` is one key, and `NaN` and `NA` are separate
39//!   groups. Labels are R's `as.character()` of the key — see [`RealKey`]. A
40//!   bit64 `integer64` column (int64 bits stored in a double vector) is an
41//!   error.
42//!
43//! # Composite keys (`group_by_multi`)
44//!
45//! [`DataFrame::group_by_multi`] groups on several columns at once, keying by a
46//! [`GroupKey::Tuple`] of the per-column scalar keys. Non-NA groups match
47//! `split(df, interaction(col1, col2, …, drop = TRUE))` (the first column varies
48//! fastest, R `interaction()`'s default) — exactly, for keys whose byte order
49//! coincides with the session's collation (always true in the C locale;
50//! single-case ASCII in practice — the character-key byte-order choice above
51//! applies per column). Extending the single-column
52//! NA convention, any tuple with an NA in *any* component forms its own trailing
53//! group (first-encounter order) instead of being dropped as `interaction()` +
54//! `split()` would.
55
56use std::collections::{BTreeMap, HashMap};
57
58use super::{DataFrame, DataFrameError, FromDataFrame};
59use crate::into_r::IntoR;
60use crate::{IsNA, SEXP, SEXPTYPE, SexpExt};
61
62// region: group_rows — typed-rows grouping helper (rung 1)
63
64/// Group already-extracted rows by a key function.
65///
66/// Plain Rust — no SEXP contact, so the result is `Send` (given `T: Send`) and
67/// safe to iterate with rayon. Keys order by `Ord`; give NA-able keys a home by
68/// keying on `Option<T>` (`None` sorts first) or a custom enum.
69pub fn group_rows<T, K, F>(rows: Vec<T>, key: F) -> BTreeMap<K, Vec<T>>
70where
71    K: Ord,
72    F: Fn(&T) -> K,
73{
74    let mut groups: BTreeMap<K, Vec<T>> = BTreeMap::new();
75    for row in rows {
76        groups.entry(key(&row)).or_default().push(row);
77    }
78    groups
79}
80// endregion
81
82// region: GroupKey
83
84/// The key of one group produced by [`DataFrame::group_by`] or
85/// [`DataFrame::group_by_multi`].
86#[derive(#[automatically_derived]impl ::core::fmt::Debug for GroupKey {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        match self {
            Self::Str(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f, "Str",
                    &__self_0),
            Self::Int(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f, "Int",
                    &__self_0),
            Self::Real(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f, "Real",
                    &__self_0),
            Self::Bool(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f, "Bool",
                    &__self_0),
            Self::Na => ::core::fmt::Formatter::write_str(f, "Na"),
            Self::Tuple(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f, "Tuple",
                    &__self_0),
        }
    }
}Debug, #[automatically_derived]impl ::core::clone::Clone for GroupKey {
    #[inline]
    fn clone(&self) -> Self {
        match self {
            Self::Str(__self_0) =>
                GroupKey::Str(::core::clone::Clone::clone(__self_0)),
            Self::Int(__self_0) =>
                GroupKey::Int(::core::clone::Clone::clone(__self_0)),
            Self::Real(__self_0) =>
                GroupKey::Real(::core::clone::Clone::clone(__self_0)),
            Self::Bool(__self_0) =>
                GroupKey::Bool(::core::clone::Clone::clone(__self_0)),
            Self::Na => GroupKey::Na,
            Self::Tuple(__self_0) =>
                GroupKey::Tuple(::core::clone::Clone::clone(__self_0)),
        }
    }
}Clone, #[automatically_derived]impl ::core::marker::StructuralPartialEq for GroupKey
    {
}
#[automatically_derived]impl ::core::cmp::PartialEq for GroupKey {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        ::core::intrinsics::discriminant_value(self) ==
                ::core::intrinsics::discriminant_value(other) &&
            match (self, other) {
                (Self::Str(__self_0), Self::Str(__arg1_0)) =>
                    __self_0 == __arg1_0,
                (Self::Int(__self_0), Self::Int(__arg1_0)) =>
                    __self_0 == __arg1_0,
                (Self::Real(__self_0), Self::Real(__arg1_0)) =>
                    __self_0 == __arg1_0,
                (Self::Bool(__self_0), Self::Bool(__arg1_0)) =>
                    __self_0 == __arg1_0,
                (Self::Tuple(__self_0), Self::Tuple(__arg1_0)) =>
                    __self_0 == __arg1_0,
                _ => true,
            }
    }
}PartialEq, #[automatically_derived]impl ::core::cmp::Eq for GroupKey {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {
        let _: ::core::cmp::AssertParamIsEq<String>;
        let _: ::core::cmp::AssertParamIsEq<i32>;
        let _: ::core::cmp::AssertParamIsEq<RealKey>;
        let _: ::core::cmp::AssertParamIsEq<bool>;
        let _: ::core::cmp::AssertParamIsEq<Vec<GroupKey>>;
    }
}Eq, #[automatically_derived]impl ::core::hash::Hash for GroupKey {
    #[inline]
    fn hash<__H: ::core::hash::Hasher>(&self, state: &mut __H) {
        ::core::hash::Hash::hash(&::core::intrinsics::discriminant_value(self),
            state);
        match self {
            Self::Str(__self_0) => ::core::hash::Hash::hash(__self_0, state),
            Self::Int(__self_0) => ::core::hash::Hash::hash(__self_0, state),
            Self::Real(__self_0) => ::core::hash::Hash::hash(__self_0, state),
            Self::Bool(__self_0) => ::core::hash::Hash::hash(__self_0, state),
            Self::Tuple(__self_0) =>
                ::core::hash::Hash::hash(__self_0, state),
            _ => {}
        }
    }
}Hash)]
87pub enum GroupKey {
88    /// A character or factor-level key.
89    Str(String),
90    /// An integer key.
91    Int(i32),
92    /// A double key: a plain number, a `Date`, a `POSIXct`, or another classed
93    /// double. See [`RealKey`] for its equality and label.
94    Real(RealKey),
95    /// A logical key.
96    Bool(bool),
97    /// The NA-keyed group (always ordered last).
98    Na,
99    /// A composite key from [`DataFrame::group_by_multi`] — one scalar element
100    /// per grouping column, in column order. Elements are always scalar
101    /// ([`Str`](Self::Str)/[`Int`](Self::Int)/[`Real`](Self::Real)/[`Bool`](Self::Bool)/[`Na`](Self::Na));
102    /// tuples never nest (enforced by a `debug_assert!` in [`label`](Self::label)).
103    Tuple(Vec<GroupKey>),
104}
105
106impl GroupKey {
107    /// R-facing label for this key — suitable as a name in a result list
108    /// (matches how R prints the value: `TRUE`/`FALSE`, `NA`, digits, and R's
109    /// `as.character()` text for a [`Real`](Self::Real) key). Composite
110    /// [`Tuple`](Self::Tuple) keys join their element labels with `"."`, matching
111    /// R `interaction()`'s default separator.
112    pub fn label(&self) -> String {
113        match self {
114            GroupKey::Str(s) => s.clone(),
115            GroupKey::Int(i) => i.to_string(),
116            GroupKey::Real(r) => r.label.clone(),
117            GroupKey::Bool(true) => "TRUE".to_string(),
118            GroupKey::Bool(false) => "FALSE".to_string(),
119            GroupKey::Na => "NA".to_string(),
120            GroupKey::Tuple(keys) => {
121                if true {
    if !keys.iter().all(|k|
                    !#[allow(non_exhaustive_omitted_patterns)] match k {
                            GroupKey::Tuple(_) => true,
                            _ => false,
                        }) {
        {
            ::core::panicking::panic_fmt(format_args!("tuple keys never nest — elements come from scalar columns"));
        }
    };
};debug_assert!(
122                    keys.iter().all(|k| !matches!(k, GroupKey::Tuple(_))),
123                    "tuple keys never nest — elements come from scalar columns"
124                );
125                keys.iter()
126                    .map(GroupKey::label)
127                    .collect::<Vec<_>>()
128                    .join(".")
129            }
130        }
131    }
132}
133
134impl std::fmt::Display for GroupKey {
135    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
136        match self {
137            GroupKey::Str(s) => f.write_str(s),
138            GroupKey::Int(i) => f.write_fmt(format_args!("{0}", i))write!(f, "{}", i),
139            GroupKey::Real(r) => f.write_str(&r.label),
140            GroupKey::Bool(true) => f.write_str("TRUE"),
141            GroupKey::Bool(false) => f.write_str("FALSE"),
142            GroupKey::Na => f.write_str("NA"),
143            GroupKey::Tuple(keys) => {
144                for (i, key) in keys.iter().enumerate() {
145                    if i > 0 {
146                        f.write_str(".")?;
147                    }
148                    f.write_fmt(format_args!("{0}", key))write!(f, "{}", key)?;
149                }
150                Ok(())
151            }
152        }
153    }
154}
155
156/// The key of one double-valued group ([`GroupKey::Real`]): the value plus
157/// the text R prints for it.
158///
159/// # Equality
160///
161/// Keys compare and hash by value alone, with the rules vctrs uses and
162/// therefore dplyr's `group_by()`: `-0.0` equals `0.0`, and every `NaN` is the
163/// same key. `NA_real_` is never a `RealKey`: an `NA` cell keys as
164/// [`GroupKey::Na`], so `NA` and `NaN` rows form separate groups, as in dplyr.
165/// The label takes no part in equality.
166///
167/// # Label
168///
169/// The grouping verbs label a key with R's `as.character()` of its value,
170/// called with the key column's attributes (class, `tzone`, …): the same text
171/// `factor()` and `split()` use for level names. So a plain double prints
172/// with up to 15 significant digits (`"0.1"`, `"1e+05"`, `"NaN"`), a `Date`
173/// prints as `"2024-01-02"`, and a `POSIXct` prints in the column's time zone
174/// (`"2024-01-02 10:30:00"`, or just the date at midnight).
175#[derive(#[automatically_derived]impl ::core::fmt::Debug for RealKey {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field2_finish(f,
            "RealKey value label", &self.value, &&self.label)
    }
}Debug, #[automatically_derived]impl ::core::clone::Clone for RealKey {
    #[inline]
    fn clone(&self) -> Self {
        RealKey {
            value: ::core::clone::Clone::clone(&self.value),
            label: ::core::clone::Clone::clone(&self.label),
        }
    }
}Clone)]
176pub struct RealKey {
177    value: f64,
178    label: String,
179}
180
181impl RealKey {
182    /// A key for `value`, printed as `label`. `-0.0` is stored as `0.0` and
183    /// every `NaN` as one canonical `NaN`, so equal keys hold identical bits.
184    pub fn new(value: f64, label: impl Into<String>) -> Self {
185        RealKey {
186            value: normalize_real(value),
187            label: label.into(),
188        }
189    }
190
191    /// The key's value: never `-0.0`, and `NaN` is the canonical positive
192    /// quiet `NaN`. For a `Date` key this is days since 1970-01-01; for a
193    /// `POSIXct` key, seconds since the epoch.
194    pub fn value(&self) -> f64 {
195        self.value
196    }
197
198    /// The text R prints for the key (see the [type docs](Self)).
199    pub fn label(&self) -> &str {
200        &self.label
201    }
202}
203
204impl PartialEq for RealKey {
205    fn eq(&self, other: &Self) -> bool {
206        self.value.to_bits() == other.value.to_bits()
207    }
208}
209
210impl Eq for RealKey {}
211
212impl std::hash::Hash for RealKey {
213    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
214        self.value.to_bits().hash(state);
215    }
216}
217
218/// Bits of the one `NaN` every `NaN` key is stored as: positive and quiet, so
219/// [`f64::total_cmp`] orders it after `+Inf` on every platform (x86's `0/0` has
220/// the sign bit set), and its low word is not R's NA payload (1954).
221const CANONICAL_NAN_BITS: u64 = 0x7FF8_0000_0000_0000;
222
223/// Map a non-NA double to its key representative: `-0.0` → `0.0`, any `NaN`
224/// → the canonical `NaN`. Equal keys (by vctrs' rules) then share their bits.
225fn normalize_real(x: f64) -> f64 {
226    if x == 0.0 {
227        0.0
228    } else if x.is_nan() {
229        f64::from_bits(CANONICAL_NAN_BITS)
230    } else {
231        x
232    }
233}
234// endregion
235
236// region: GroupDeclaration
237
238/// How a dplyr-grouped frame declares its grouping, returned by
239/// [`DataFrame::group_declaration`]: the grouping variables and the `.drop`
240/// policy, without the cached group rows.
241#[derive(#[automatically_derived]impl ::core::fmt::Debug for GroupDeclaration {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field2_finish(f,
            "GroupDeclaration vars drop", &self.vars, &&self.drop)
    }
}Debug, #[automatically_derived]impl ::core::clone::Clone for GroupDeclaration {
    #[inline]
    fn clone(&self) -> Self {
        GroupDeclaration {
            vars: ::core::clone::Clone::clone(&self.vars),
            drop: ::core::clone::Clone::clone(&self.drop),
        }
    }
}Clone, #[automatically_derived]impl ::core::marker::StructuralPartialEq for
    GroupDeclaration {
}
#[automatically_derived]impl ::core::cmp::PartialEq for GroupDeclaration {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.drop == other.drop && self.vars == other.vars
    }
}PartialEq, #[automatically_derived]impl ::core::cmp::Eq for GroupDeclaration {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {
        let _: ::core::cmp::AssertParamIsEq<Vec<String>>;
        let _: ::core::cmp::AssertParamIsEq<bool>;
    }
}Eq)]
242pub struct GroupDeclaration {
243    /// The grouping variable names, in declaration order — dplyr's
244    /// `group_vars()`, `setdiff(names(groups), ".rows")`: the `groups`
245    /// frame's column names other than `.rows`, each once. Empty for a
246    /// `rowwise_df` without id columns.
247    pub vars: Vec<String>,
248    /// Whether grouping drops empty groups — dplyr's
249    /// `group_by_drop_default()`. For a `grouped_df`, `true` unless the
250    /// `groups` frame's `.drop` attribute is exactly `FALSE`
251    /// (`identical(attr(groups, ".drop"), FALSE)`: a length-1 logical `FALSE`
252    /// with no attributes). Always `true` for a frame that is a `rowwise_df`
253    /// but not a `grouped_df`, whose `group_by_drop_default()` is the default
254    /// method's `TRUE`.
255    pub drop: bool,
256}
257
258/// A grouped frame's `groups` attribute after the structural checks of
259/// [`DataFrame::groups_attr`].
260struct GroupsAttr {
261    /// The `groups` data frame: a list inheriting from `data.frame`, with at
262    /// least one column.
263    frame: SEXP,
264    /// Its last column, `.rows`: a list of integer vectors, one per group.
265    rows: SEXP,
266}
267
268impl GroupsAttr {
269    /// The grouping-variable columns, by position, with their names: every
270    /// column not named `.rows`, keeping only the first column of a repeated
271    /// name. Their names are dplyr's `group_vars()`,
272    /// `setdiff(names(groups), ".rows")`. An `NA` name reads as `""`, as in
273    /// [`DataFrame::names`]; a name that is not text (marked as bytes) is an
274    /// error, every one listed.
275    fn key_columns(&self) -> Result<Vec<(String, SEXP)>, DataFrameError> {
276        let names = self.frame.get_names();
277        let mut columns: Vec<(String, SEXP)> = Vec::new();
278        let mut errors = crate::from_r::BatchedErrors::default();
279        for i in 0..self.frame.len() {
280            let charsxp = names.string_elt(i as isize);
281            let name = if charsxp.is_na_string() {
282                ""
283            } else {
284                match text_key(charsxp, i, "", &mut errors) {
285                    Some(name) => name,
286                    None => continue,
287                }
288            };
289            if name == ".rows" || columns.iter().any(|(seen, _)| seen == name) {
290                continue;
291            }
292            columns.push((name.to_string(), self.frame.vector_elt(i as isize)));
293        }
294        if !errors.is_empty() {
295            return Err(DataFrameError::Conversion(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("cannot read the grouping variable names: {0}",
                errors.element_message()))
    })format!(
296                "cannot read the grouping variable names: {}",
297                errors.element_message()
298            )));
299        }
300        Ok(columns)
301    }
302}
303// endregion
304
305// region: GroupedDataFrame
306
307/// A [`DataFrame`] partitioned by the values of one key column.
308///
309/// Produced by [`DataFrame::group_by`]. Holds the source frame plus one
310/// `(key, row-indices)` pair per group; nothing is copied until you ask for
311/// [`frames`](Self::frames) or [`extract`](Self::extract).
312///
313/// # GC rooting
314///
315/// The source frame is preserved on R's precious list
316/// (`R_PreserveObject`) for this struct's lifetime and released on drop —
317/// order-independent, unlike the PROTECT stack, so the struct can be held
318/// across arbitrary allocations (e.g. a locally built frame from
319/// [`DataFrame::builder`], which is unprotected once `build()` returns).
320/// Without this, the per-group allocations in [`frames`](Self::frames) /
321/// [`extract`](Self::extract) could collect the source mid-iteration.
322/// Main-thread-only (holds a SEXP; `!Send`).
323pub struct GroupedDataFrame {
324    source: DataFrame,
325    groups: Vec<(GroupKey, Vec<usize>)>,
326}
327
328impl Drop for GroupedDataFrame {
329    fn drop(&mut self) {
330        // SAFETY: main thread (construction invariant — SEXP is !Send);
331        // releases the preserve taken in `group_by`.
332        unsafe { crate::sys::R_ReleaseObject(self.source.as_sexp()) };
333    }
334}
335
336impl GroupedDataFrame {
337    /// Root `source` on R's precious list and pair it with precomputed groups.
338    ///
339    /// `R_PreserveObject` conses onto the precious list — an allocation that can
340    /// itself GC — so PROTECT `source` across the call. Released on `Drop`.
341    fn new(source: DataFrame, groups: Vec<(GroupKey, Vec<usize>)>) -> Self {
342        unsafe {
343            let _guard = crate::OwnedProtect::new(source.sexp);
344            crate::sys::R_PreserveObject(source.sexp);
345        }
346        GroupedDataFrame { source, groups }
347    }
348
349    /// Number of groups (empty factor levels included).
350    pub fn len(&self) -> usize {
351        self.groups.len()
352    }
353
354    /// Whether there are no groups.
355    pub fn is_empty(&self) -> bool {
356        self.groups.is_empty()
357    }
358
359    /// The frame this grouping was computed from.
360    pub fn source(&self) -> &DataFrame {
361        &self.source
362    }
363
364    /// Iterate `(key, row-indices)` pairs in group order. Indices are 0-based
365    /// rows of [`source`](Self::source).
366    pub fn iter(&self) -> impl Iterator<Item = (&GroupKey, &[usize])> {
367        self.groups.iter().map(|(k, idx)| (k, idx.as_slice()))
368    }
369
370    /// Iterate `(key, sub-frame)` pairs, materialising each group as its own
371    /// frame via [`DataFrame::select_rows`].
372    ///
373    /// Main thread only. Each yielded frame is an owned, GC-rooted
374    /// [`BuiltDataFrame`](crate::dataframe::BuiltDataFrame) (#1247) — safe to
375    /// hold across later iterations' allocations. Pass each handle directly to
376    /// [`NamedListBuilder::push`](crate::NamedListBuilder::push)
377    /// to collect the frames into an owned named list.
378    pub fn frames(&self) -> impl Iterator<Item = (&GroupKey, crate::dataframe::BuiltDataFrame)> {
379        self.groups
380            .iter()
381            .map(|(k, idx)| (k, self.source.select_rows(idx)))
382    }
383
384    /// Extract typed rows once, then partition them by group.
385    ///
386    /// One `Vec::<T>::from_dataframe` pass over the whole frame, then a
387    /// move-partition by the stored indices — no per-group R subsetting and no
388    /// `Clone` bound. The result is plain Rust data (rayon-safe afterwards).
389    pub fn extract<T>(&self) -> Result<Vec<(GroupKey, Vec<T>)>, DataFrameError>
390    where
391        Vec<T>: FromDataFrame,
392    {
393        let rows = Vec::<T>::from_dataframe(&self.source)?;
394        let mut slots: Vec<Option<T>> = rows.into_iter().map(Some).collect();
395        Ok(self
396            .groups
397            .iter()
398            .map(|(key, idx)| {
399                let group_rows: Vec<T> = idx
400                    .iter()
401                    .map(|&i| slots[i].take().expect("group indices are disjoint"))
402                    .collect();
403                (key.clone(), group_rows)
404            })
405            .collect())
406    }
407}
408// endregion
409
410// region: DataFrame::group_by
411
412impl DataFrame {
413    /// Partition this frame's rows by the values of the named column.
414    ///
415    /// Computes group indices in a single pass on the main thread. Supported
416    /// key columns: factor (fast path — levels are the keys, level order kept,
417    /// empty levels included), character, integer, logical, and double
418    /// (`Date` and `POSIXct` included; keyed as [`GroupKey::Real`], labelled by
419    /// R's `as.character()`). List columns and bit64 `integer64` columns are an
420    /// error.
421    ///
422    /// NA keys form one group, ordered last (unlike R `split()`, which drops
423    /// NA-keyed rows). See the [module docs](self) for the full key semantics.
424    pub fn group_by(&self, col: &str) -> Result<GroupedDataFrame, DataFrameError> {
425        let column = self
426            .column_raw(col)
427            .ok_or_else(|| DataFrameError::NoSuchColumn(col.to_string()))?;
428        let groups = column_groups(column, col)?;
429        // Root the source for the GroupedDataFrame's lifetime (see its GC
430        // rooting docs).
431        Ok(GroupedDataFrame::new(*self, groups))
432    }
433
434    /// Partition this frame's rows by a composite key over several columns —
435    /// the multi-column analogue of [`group_by`](Self::group_by).
436    ///
437    /// Each supported column contributes one scalar key per row (factor level,
438    /// character, integer, logical, or double — same rules and errors as
439    /// [`group_by`](Self::group_by)); the per-row keys are zipped into a
440    /// [`GroupKey::Tuple`] in column order.
441    ///
442    /// # Order
443    ///
444    /// Non-NA groups match `split(df, interaction(col1, col2, …, drop = TRUE))`:
445    /// the **first** column varies fastest (R `interaction()`'s default,
446    /// `lex.order = FALSE`), each column ordered as [`group_by`](Self::group_by)
447    /// would order it alone (factor level order, byte-sorted characters, numeric
448    /// integers and doubles — `NaN` after every number — and `FALSE` then
449    /// `TRUE`). For character keys the match is exact for
450    /// keys whose byte order coincides with the session's collation — always
451    /// true in the C locale; single-case ASCII in practice (e.g. `en_US.UTF-8`
452    /// collates `a A b B` where byte order gives `A B a b`). This is inherited
453    /// from [`group_by`](Self::group_by)'s byte-order choice for character keys
454    /// — see the group-order note in the [module docs](self).
455    ///
456    /// # NA
457    ///
458    /// `interaction()` maps any row with an NA in *any* component to NA and
459    /// `split()` drops it. This method instead keeps such rows: every distinct
460    /// NA-containing tuple forms its own group, all ordered **after** the non-NA
461    /// groups, in first-encounter row order. This extends the single-column
462    /// NA-last convention (see the [module docs](self)).
463    ///
464    /// # Slice
465    ///
466    /// An empty slice is an error. A single-column slice delegates to
467    /// [`group_by`](Self::group_by) and yields **scalar** keys (not 1-tuples), so
468    /// callers never have to special-case one-element tuples.
469    pub fn group_by_multi(&self, cols: &[&str]) -> Result<GroupedDataFrame, DataFrameError> {
470        if cols.is_empty() {
471            return Err(DataFrameError::EmptyGroupColumns);
472        }
473        // A single column is the scalar path — identical keys/order to group_by.
474        if let [col] = cols {
475            return self.group_by(col);
476        }
477
478        // One grouping pass per column gives both the per-row keys (to build
479        // the tuples) and the column's group order (an ordinal per non-NA key,
480        // for sorting). NA is excluded from the ordinals: NA-containing tuples
481        // are ordered separately below.
482        let mut per_row: Vec<Vec<GroupKey>> = Vec::with_capacity(cols.len());
483        let mut ordinals: Vec<HashMap<GroupKey, usize>> = Vec::with_capacity(cols.len());
484        for &col in cols {
485            let column = self
486                .column_raw(col)
487                .ok_or_else(|| DataFrameError::NoSuchColumn(col.to_string()))?;
488            let groups = column_groups(column, col)?;
489            per_row.push(row_keys(&groups, column.len()));
490            ordinals.push(
491                groups
492                    .into_iter()
493                    .map(|(key, _)| key)
494                    .filter(|key| !#[allow(non_exhaustive_omitted_patterns)] match key {
    GroupKey::Na => true,
    _ => false,
}matches!(key, GroupKey::Na))
495                    .enumerate()
496                    .map(|(ord, key)| (key, ord))
497                    .collect(),
498            );
499        }
500
501        // Bucket rows into tuple keys, preserving first-encounter order.
502        let mut index: HashMap<GroupKey, usize> = HashMap::new();
503        let mut buckets: Vec<(GroupKey, Vec<usize>)> = Vec::new();
504        for (row, first) in per_row[0].iter().enumerate() {
505            let mut elems = Vec::with_capacity(cols.len());
506            elems.push(first.clone());
507            for col in &per_row[1..] {
508                elems.push(col[row].clone());
509            }
510            let key = GroupKey::Tuple(elems);
511            match index.get(&key) {
512                Some(&pos) => buckets[pos].1.push(row),
513                None => {
514                    index.insert(key.clone(), buckets.len());
515                    buckets.push((key, ::alloc::boxed::box_assume_init_into_vec_unsafe(::alloc::intrinsics::write_box_via_move(::alloc::boxed::Box::new_uninit(),
        [row]))vec![row]));
516                }
517            }
518        }
519
520        // Non-NA tuples order by interaction() convention (first column varies
521        // fastest → last column is the most-significant sort key). NA-containing
522        // tuples trail, in first-encounter order (already the bucket order).
523        let is_na_tuple = |k: &GroupKey| #[allow(non_exhaustive_omitted_patterns)] match k {
    GroupKey::Tuple(elems) if
        elems.iter().any(|e|
                #[allow(non_exhaustive_omitted_patterns)] match e {
                    GroupKey::Na => true,
                    _ => false,
                }) => true,
    _ => false,
}matches!(k, GroupKey::Tuple(elems) if elems.iter().any(|e| matches!(e, GroupKey::Na)));
524        let (mut non_na, na_tuples): (Vec<_>, Vec<_>) =
525            buckets.into_iter().partition(|(k, _)| !is_na_tuple(k));
526        non_na.sort_by_key(|(k, _)| {
527            let GroupKey::Tuple(elems) = k else {
528                {
    ::core::panicking::panic_fmt(format_args!("internal error: entered unreachable code: {0}",
            format_args!("group_by_multi buckets are always tuples")));
}unreachable!("group_by_multi buckets are always tuples")
529            };
530            let mut ord: Vec<usize> = elems
531                .iter()
532                .enumerate()
533                .map(|(c, e)| ordinals[c][e])
534                .collect();
535            ord.reverse();
536            ord
537        });
538        non_na.extend(na_tuples);
539
540        Ok(GroupedDataFrame::new(*self, non_na))
541    }
542
543    /// Read a dplyr-grouped frame's grouping **declaration** — its grouping
544    /// variables and `.drop` policy — without its cached group rows.
545    ///
546    /// Returns what dplyr's `group_vars()` and `group_by_drop_default()`
547    /// report: `Ok(None)` when the frame is not grouped, and an error when it
548    /// is grouped but its `groups` attribute is corrupt, where `group_vars()`
549    /// errors too (see below). Nothing is partitioned and no row index is
550    /// read, so the key-column types and whether the cached `.rows` still fit
551    /// the frame never matter. A function that groups the frame's **current**
552    /// rows itself (e.g. with [`group_by_multi`](Self::group_by_multi) over
553    /// [`GroupDeclaration::vars`]) reads this instead of
554    /// [`group_by_metadata`](Self::group_by_metadata), which trusts the cached
555    /// rows.
556    ///
557    /// # Grouped frames
558    ///
559    /// A frame is grouped when it inherits from `grouped_df` or `rowwise_df`,
560    /// whatever its attributes: `dplyr::is_grouped_df()` is
561    /// `inherits(x, "grouped_df")`. A plain `data.frame` with a stray `groups`
562    /// attribute is not grouped (`Ok(None)`).
563    ///
564    /// # Errors
565    ///
566    /// A grouped frame's `groups` attribute must pass the structural checks
567    /// of dplyr's `validate_grouped_df()`, which `group_vars()` runs on a
568    /// `grouped_df`: it is a data frame ([`GroupsNotDataFrame`]), its last
569    /// column is called `.rows` ([`MissingGroupRows`]), and that column is a
570    /// list of integer vectors ([`BadGroupRows`]; a list of doubles is
571    /// rejected, as in dplyr). The row indices themselves are not checked,
572    /// as `group_vars()` does not check them either, so stale `.rows` after a
573    /// subset still yield the declaration. A grouping-variable name marked as
574    /// bytes is a [`Conversion`](DataFrameError::Conversion) error.
575    ///
576    /// A `rowwise_df` gets the same checks. dplyr is looser here:
577    /// `group_vars()` reads a `rowwise_df`'s `groups` attribute without
578    /// validating it. `validate_rowwise_df()` applies the same checks, plus
579    /// row-shape checks that this method skips (one `.rows` element per row,
580    /// each holding its own row number).
581    ///
582    /// [`GroupsNotDataFrame`]: DataFrameError::GroupsNotDataFrame
583    /// [`MissingGroupRows`]: DataFrameError::MissingGroupRows
584    /// [`BadGroupRows`]: DataFrameError::BadGroupRows
585    ///
586    /// # Example
587    ///
588    /// ```ignore
589    /// // df arrived as dplyr::group_by(data, site, .drop = FALSE)
590    /// let decl = df.group_declaration()?.expect("a grouped_df");
591    /// assert_eq!(decl.vars, ["site"]);
592    /// assert!(!decl.drop);
593    /// ```
594    pub fn group_declaration(&self) -> Result<Option<GroupDeclaration>, DataFrameError> {
595        let Some(groups) = self.groups_attr()? else {
596            return Ok(None);
597        };
598        // group_by_drop_default(): only its grouped_df method reads `.drop`,
599        // as `!identical(attr(groups, ".drop"), FALSE)` with identical()'s
600        // default flags. A frame that is only a rowwise_df gets the default
601        // method's TRUE. `Rf_ScalarLogical(0)` returns R's shared FALSE
602        // without allocating.
603        let drop = !self.sexp.inherits_class(c"grouped_df") || {
604            let drop_attr = groups
605                .frame
606                .get_attr(unsafe { crate::sys::Rf_install(c".drop".as_ptr()) });
607            unsafe {
608                crate::sys::R_compute_identical(
609                    drop_attr,
610                    crate::sys::Rf_ScalarLogical(0),
611                    crate::sys::IDENT_USE_CLOENV,
612                ) == crate::sexp_types::Rboolean::FALSE
613            }
614        };
615        Ok(Some(GroupDeclaration {
616            vars: groups
617                .key_columns()?
618                .into_iter()
619                .map(|(name, _)| name)
620                .collect(),
621            drop,
622        }))
623    }
624
625    /// Ingest a dplyr `grouped_df`'s existing grouping from its `groups`
626    /// attribute — **honoring the caller's grouping without recomputing it**.
627    ///
628    /// dplyr stores a `grouped_df`'s grouping in `attr(df, "groups")`: a
629    /// `data.frame` whose leading columns are the group-key columns (one row
630    /// per group, in dplyr's group order) and whose trailing `.rows`
631    /// list-column holds, per group, the 1-based row indices into `df`. This
632    /// method reads that metadata verbatim into a [`GroupedDataFrame`] — the
633    /// same type [`group_by`](Self::group_by) / [`group_by_multi`](Self::group_by_multi)
634    /// produce — so a `#[miniextendr]` function handed a dplyr-grouped frame can
635    /// respect the caller's grouping, including multi-column groupings.
636    ///
637    /// Unlike [`group_by`](Self::group_by), this does **no** recomputation: a
638    /// frame that is not grouped (see [`group_declaration`](Self::group_declaration)
639    /// for the test) is an error ([`NotGroupedDataFrame`]). Callers who want the
640    /// framework to compute grouping should use [`group_by`](Self::group_by) /
641    /// [`group_by_multi`](Self::group_by_multi).
642    ///
643    /// # Keys
644    ///
645    /// A single key column yields scalar [`GroupKey`]s; multiple key columns
646    /// yield [`GroupKey::Tuple`]s (labels `.`-joined), consistent with
647    /// [`group_by_multi`](Self::group_by_multi). Supported key-column types are
648    /// the same as [`group_by`](Self::group_by) (factor, character, integer,
649    /// logical, double — `Date` and `POSIXct` included); a list / `integer64`
650    /// key column is an error.
651    ///
652    /// # Order & empty groups
653    ///
654    /// The `groups`-frame row order is preserved verbatim — dplyr's order is
655    /// authoritative, with no re-sorting and no NA reordering. `.drop = FALSE`
656    /// empty groups (zero-length `.rows`) are **kept** as groups with empty
657    /// index vectors, mirroring the empty-factor-level convention of
658    /// [`group_by`](Self::group_by).
659    ///
660    /// # Trusts the cached rows
661    ///
662    /// The `.rows` are dplyr's cache of the grouping, and this method uses them
663    /// as they are. It checks that they still fit the frame — every index in
664    /// `1..=nrow`, every row in exactly one group — and reports stale metadata
665    /// otherwise ([`GroupIndexOutOfRange`], [`GroupRowUncovered`],
666    /// [`GroupRowDuplicated`]). The usual cause is subsetting a grouped frame
667    /// without dplyr loaded: `[` then keeps the old `groups` attribute. It does
668    /// **not** compare the rows' key values with their group's key, so a pure
669    /// reorder done the same way (`df[c(3, 4, 1, 2), ]`) still fits and yields
670    /// the old row positions (#1687). To group the current rows instead, read
671    /// the declaration with [`group_declaration`](Self::group_declaration) and
672    /// group by its variables.
673    ///
674    /// # Errors
675    ///
676    /// [`NotGroupedDataFrame`] (not grouped); for a corrupt `groups`
677    /// attribute, the errors [`group_declaration`](Self::group_declaration)
678    /// reports ([`GroupsNotDataFrame`], [`MissingGroupRows`],
679    /// [`BadGroupRows`]: `.rows` must be a list of integer vectors, so a
680    /// list of doubles is rejected, as in dplyr); [`UnequalLengths`] (a key
681    /// column's length differs from that of `.rows`);
682    /// [`UnsupportedGroupColumn`] (a key column of an unsupported type); or
683    /// one of the stale-metadata errors above. Every `.rows` index is
684    /// converted from R's 1-based to 0-based.
685    ///
686    /// [`NotGroupedDataFrame`]: DataFrameError::NotGroupedDataFrame
687    /// [`GroupsNotDataFrame`]: DataFrameError::GroupsNotDataFrame
688    /// [`MissingGroupRows`]: DataFrameError::MissingGroupRows
689    /// [`BadGroupRows`]: DataFrameError::BadGroupRows
690    /// [`UnequalLengths`]: DataFrameError::UnequalLengths
691    /// [`UnsupportedGroupColumn`]: DataFrameError::UnsupportedGroupColumn
692    /// [`GroupIndexOutOfRange`]: DataFrameError::GroupIndexOutOfRange
693    /// [`GroupRowUncovered`]: DataFrameError::GroupRowUncovered
694    /// [`GroupRowDuplicated`]: DataFrameError::GroupRowDuplicated
695    ///
696    /// # GC
697    ///
698    /// The `groups` attribute frame (and its columns) is only read here, during
699    /// construction; it stays reachable via `self`'s attribute pairlist — which
700    /// R protects as a `.Call` argument frame for the duration of the call — so
701    /// it needs no separate root. Only the returned [`GroupedDataFrame`] roots
702    /// the **source** frame for its own lifetime (see its GC-rooting docs).
703    pub fn group_by_metadata(&self) -> Result<GroupedDataFrame, DataFrameError> {
704        let attr = self
705            .groups_attr()?
706            .ok_or(DataFrameError::NotGroupedDataFrame)?;
707        let n_groups = attr.rows.len();
708        let key_columns = attr.key_columns()?;
709
710        // Per-key-column keys: one Vec<GroupKey> of length n_groups per key
711        // column (column_keys yields one scalar key per row of the groups frame).
712        let mut per_col_keys: Vec<Vec<GroupKey>> = Vec::with_capacity(key_columns.len());
713        for (name, column) in &key_columns {
714            let keys = column_keys(*column, name)?;
715            if keys.len() != n_groups {
716                return Err(DataFrameError::UnequalLengths {
717                    expected: n_groups,
718                    columns: ::alloc::boxed::box_assume_init_into_vec_unsafe(::alloc::intrinsics::write_box_via_move(::alloc::boxed::Box::new_uninit(),
        [(name.clone(), keys.len())]))vec![(name.clone(), keys.len())],
719                });
720            }
721            per_col_keys.push(keys);
722        }
723
724        let nrow = self.nrow();
725        let single_key = key_columns.len() == 1;
726
727        let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(n_groups);
728        for g in 0..n_groups {
729            // Build this group's key: scalar for a single key column, otherwise
730            // a Tuple in column order (`.`-joined labels, like group_by_multi).
731            let key = if single_key {
732                per_col_keys[0][g].clone()
733            } else {
734                GroupKey::Tuple(per_col_keys.iter().map(|col| col[g].clone()).collect())
735            };
736            // Convert `.rows[[g]]` (1-based indices) to a validated 0-based Vec.
737            let elt = attr.rows.vector_elt(g as isize);
738            let indices = group_rows_indices(elt, g, nrow)?;
739            groups.push((key, indices));
740        }
741        // Every index is in range; now the rows must partition the frame.
742        check_rows_partition(&groups, nrow)?;
743
744        Ok(GroupedDataFrame::new(*self, groups))
745    }
746
747    /// The `groups` attribute of a dplyr-grouped frame, checked the way
748    /// dplyr's `validate_grouped_df()` checks it (with its default
749    /// `check_bounds = FALSE`).
750    ///
751    /// `Ok(None)` when the frame inherits from neither `grouped_df` nor
752    /// `rowwise_df`. Otherwise the attribute must be a data frame with at
753    /// least one column ([`DataFrameError::GroupsNotDataFrame`]), whose last
754    /// column is called `.rows` ([`DataFrameError::MissingGroupRows`]) and is
755    /// a list of integer vectors ([`DataFrameError::BadGroupRows`]). These are
756    /// dplyr's tests: `inherits(groups, "data.frame")` with at least one
757    /// column, the last name, `typeof(.rows) == "list"`, and every element's
758    /// `typeof() == "integer"`. `.rows` and the key columns are read by
759    /// position, so a column named `.rows` elsewhere in the frame is not
760    /// mistaken for it.
761    fn groups_attr(&self) -> Result<Option<GroupsAttr>, DataFrameError> {
762        if !(self.sexp.inherits_class(c"grouped_df") || self.sexp.inherits_class(c"rowwise_df")) {
763            return Ok(None);
764        }
765        let groups_sym = unsafe { crate::sys::Rf_install(c"groups".as_ptr()) };
766        let frame = self.sexp.get_attr(groups_sym);
767        // dplyr reads the columns with VECTOR_ELT, so the frame must be a list.
768        if frame.type_of() != SEXPTYPE::VECSXP || !frame.is_data_frame() || frame.len() == 0 {
769            return Err(DataFrameError::GroupsNotDataFrame);
770        }
771        let names = frame.get_names();
772        let last_is_rows = names.type_of() == SEXPTYPE::STRSXP
773            && names.len() == frame.len()
774            && crate::list::text_name(names.string_elt(names.len() as isize - 1)) == Some(".rows");
775        if !last_is_rows {
776            return Err(DataFrameError::MissingGroupRows);
777        }
778        let rows = frame.vector_elt(frame.len() as isize - 1);
779        if rows.type_of() != SEXPTYPE::VECSXP {
780            return Err(DataFrameError::BadGroupRows {
781                group: None,
782                type_of: r_typeof(rows),
783            });
784        }
785        for group in 0..rows.len() {
786            let elt = rows.vector_elt(group as isize);
787            if elt.type_of() != SEXPTYPE::INTSXP {
788                return Err(DataFrameError::BadGroupRows {
789                    group: Some(group),
790                    type_of: r_typeof(elt),
791                });
792            }
793        }
794        Ok(Some(GroupsAttr { frame, rows }))
795    }
796}
797
798/// R's `typeof()` of `x`: `"double"`, `"NULL"`, `"list"`, ….
799fn r_typeof(x: SEXP) -> String {
800    // SAFETY: Rf_type2char returns a static C string for every SEXPTYPE.
801    unsafe { std::ffi::CStr::from_ptr(crate::sys::Rf_type2char(x.type_of())) }
802        .to_string_lossy()
803        .into_owned()
804}
805
806/// Convert one `.rows` list element — an integer vector of 1-based row
807/// indices ([`DataFrame::groups_attr`] checked its type) — into 0-based
808/// indices, rejecting any index outside `1..=nrow` (`NA` included).
809fn group_rows_indices(elt: SEXP, group: usize, nrow: usize) -> Result<Vec<usize>, DataFrameError> {
810    // SAFETY: element is INTSXP (checked by groups_attr); as_slice handles
811    // empty vectors.
812    let values: &[i32] = unsafe { elt.as_slice() };
813    values
814        .iter()
815        .map(|&value| match usize::try_from(value) {
816            Ok(row) if (1..=nrow).contains(&row) => Ok(row - 1),
817            _ => Err(DataFrameError::GroupIndexOutOfRange {
818                group,
819                value: i64::from(value),
820                nrow,
821            }),
822        })
823        .collect()
824}
825
826/// Check that in-range `.rows` cover each of the frame's `nrow` rows exactly
827/// once — the shape dplyr always maintains. The first row claimed twice, or
828/// else the first row no group claims, is reported.
829fn check_rows_partition(
830    groups: &[(GroupKey, Vec<usize>)],
831    nrow: usize,
832) -> Result<(), DataFrameError> {
833    let mut owner: Vec<Option<usize>> = ::alloc::vec::from_elem_global(None, nrow)vec![None; nrow];
834    for (group, (_, rows)) in groups.iter().enumerate() {
835        for &row in rows {
836            if let Some(first_group) = owner[row] {
837                return Err(DataFrameError::GroupRowDuplicated {
838                    row,
839                    first_group,
840                    second_group: group,
841                });
842            }
843            owner[row] = Some(group);
844        }
845    }
846    match owner.iter().position(Option::is_none) {
847        Some(row) => Err(DataFrameError::GroupRowUncovered { row, nrow }),
848        None => Ok(()),
849    }
850}
851
852/// One supported key column's groups, in single-column group order (NA last)
853/// — the per-type dispatch behind [`DataFrame::group_by`], and through
854/// [`column_keys`] / [`row_keys`] behind `group_by_multi` and
855/// `group_by_metadata`.
856fn column_groups(column: SEXP, col: &str) -> Result<Vec<(GroupKey, Vec<usize>)>, DataFrameError> {
857    if column.is_factor() {
858        return factor_groups(column, col);
859    }
860    let unsupported = |type_of: String| DataFrameError::UnsupportedGroupColumn {
861        column: col.to_string(),
862        type_of,
863    };
864    match column.type_of() {
865        SEXPTYPE::STRSXP => character_groups(column, col),
866        SEXPTYPE::INTSXP => Ok(integer_groups(column)),
867        SEXPTYPE::LGLSXP => Ok(logical_groups(column)),
868        // bit64 stores int64 bits in a double vector: read as doubles, its
869        // values would order wrongly, and its NA (the bits of -0.0) would
870        // join the 0 group.
871        SEXPTYPE::REALSXP if column.inherits_class(c"integer64") => {
872            Err(unsupported("integer64".to_string()))
873        }
874        SEXPTYPE::REALSXP => real_groups(column, col),
875        other => Err(unsupported(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("{0:?}", other))
    })format!("{:?}", other))),
876    }
877}
878
879/// Invert groups into one key per row (`nrow` rows, row order). Each row of a
880/// key column lands in exactly one group, so every slot is filled.
881fn row_keys(groups: &[(GroupKey, Vec<usize>)], nrow: usize) -> Vec<GroupKey> {
882    let mut keys: Vec<Option<GroupKey>> = ::alloc::vec::from_elem_global(None, nrow)vec![None; nrow];
883    for (key, rows) in groups {
884        for &row in rows {
885            keys[row] = Some(key.clone());
886        }
887    }
888    keys.into_iter()
889        .map(|key| key.expect("each row of a key column is in exactly one group"))
890        .collect()
891}
892
893/// Per-row group key for one supported key column, in row order. NA cells — and
894/// factor NA codes / `addNA()` levels — become [`GroupKey::Na`]. Same type
895/// dispatch and errors as [`DataFrame::group_by`].
896fn column_keys(column: SEXP, col: &str) -> Result<Vec<GroupKey>, DataFrameError> {
897    Ok(row_keys(&column_groups(column, col)?, column.len()))
898}
899
900/// The text of the non-`NA` key `charsxp` (element `i`), or the failure
901/// recorded in `errors`, its reason after `what`: a key marked as bytes, or
902/// not valid UTF-8, has no `String` (see
903/// [`crate::from_r::try_charsxp_to_str`]).
904fn text_key(
905    charsxp: SEXP,
906    i: usize,
907    what: &str,
908    errors: &mut crate::from_r::BatchedErrors,
909) -> Option<&'static str> {
910    // SAFETY: a non-NA CHARSXP of the key column (or its levels), which the
911    // frame roots.
912    unsafe { crate::from_r::try_charsxp_to_str(charsxp) }
913        .map_err(|e| errors.push(i, || ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("{1}{0}", e.r_reason(false), what))
    })format!("{what}{}", e.r_reason(false))))
914        .ok()
915}
916
917/// The error of a key column with keys that are not text, every one listed:
918/// `cannot group by column 'x': marked as bytes, not text (elements 2, 4)`.
919fn keys_not_text(col: &str, errors: crate::from_r::BatchedErrors) -> DataFrameError {
920    DataFrameError::Conversion(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("cannot group by column \'{1}\': {0}",
                errors.element_message(), col))
    })format!(
921        "cannot group by column '{col}': {}",
922        errors.element_message()
923    ))
924}
925
926/// Factor fast path: levels are the keys (level order, empty levels kept).
927/// NA codes — and a literal NA level from `addNA()` — land in [`GroupKey::Na`].
928/// A level that is not text (marked as bytes) is an error.
929fn factor_groups(column: SEXP, col: &str) -> Result<Vec<(GroupKey, Vec<usize>)>, DataFrameError> {
930    // SAFETY: factor columns are INTSXP; as_slice handles empty vectors.
931    let codes: &[i32] = unsafe { column.as_slice() };
932    let levels = column.get_levels();
933    let n_levels: usize = if levels.is_nil() { 0 } else { levels.len() };
934
935    let mut buckets: Vec<Vec<usize>> = ::alloc::vec::from_elem_global(Vec::new(), n_levels)vec![Vec::new(); n_levels];
936    let mut na_bucket: Vec<usize> = Vec::new();
937    for (row, &code) in codes.iter().enumerate() {
938        if code.is_na() {
939            na_bucket.push(row);
940        } else {
941            buckets[(code - 1) as usize].push(row);
942        }
943    }
944
945    let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(n_levels + 1);
946    let mut errors = crate::from_r::BatchedErrors::default();
947    for (lvl, bucket) in buckets.into_iter().enumerate() {
948        let level = levels.string_elt(lvl as isize);
949        let key = if level.is_na_string() {
950            GroupKey::Na // addNA() level
951        } else {
952            match text_key(level, lvl, "level ", &mut errors) {
953                Some(label) => GroupKey::Str(label.to_string()),
954                None => continue,
955            }
956        };
957        groups.push((key, bucket));
958    }
959    if !errors.is_empty() {
960        return Err(keys_not_text(col, errors));
961    }
962    if !na_bucket.is_empty() {
963        groups.push((GroupKey::Na, na_bucket));
964    }
965    Ok(groups)
966}
967
968/// Character keys: byte-order sort (BTreeMap), NA last. A key that is not text
969/// (marked as bytes) is an error.
970fn character_groups(
971    column: SEXP,
972    col: &str,
973) -> Result<Vec<(GroupKey, Vec<usize>)>, DataFrameError> {
974    let n = column.len();
975    let mut map: BTreeMap<String, Vec<usize>> = BTreeMap::new();
976    let mut na_bucket: Vec<usize> = Vec::new();
977    let mut errors = crate::from_r::BatchedErrors::default();
978    for i in 0..n {
979        let charsxp = column.string_elt(i as isize);
980        if charsxp.is_na_string() {
981            na_bucket.push(i);
982        } else if let Some(s) = text_key(charsxp, i, "", &mut errors) {
983            map.entry(s.to_string()).or_default().push(i);
984        }
985    }
986    if !errors.is_empty() {
987        return Err(keys_not_text(col, errors));
988    }
989    let mut groups: Vec<(GroupKey, Vec<usize>)> = map
990        .into_iter()
991        .map(|(k, idx)| (GroupKey::Str(k), idx))
992        .collect();
993    if !na_bucket.is_empty() {
994        groups.push((GroupKey::Na, na_bucket));
995    }
996    Ok(groups)
997}
998
999/// Integer keys: numeric sort (BTreeMap), NA (`i32::MIN`) last.
1000fn integer_groups(column: SEXP) -> Vec<(GroupKey, Vec<usize>)> {
1001    // SAFETY: INTSXP column; as_slice handles empty vectors.
1002    let values: &[i32] = unsafe { column.as_slice() };
1003    let mut map: BTreeMap<i32, Vec<usize>> = BTreeMap::new();
1004    let mut na_bucket: Vec<usize> = Vec::new();
1005    for (row, &v) in values.iter().enumerate() {
1006        if v.is_na() {
1007            na_bucket.push(row);
1008        } else {
1009            map.entry(v).or_default().push(row);
1010        }
1011    }
1012    let mut groups: Vec<(GroupKey, Vec<usize>)> = map
1013        .into_iter()
1014        .map(|(k, idx)| (GroupKey::Int(k), idx))
1015        .collect();
1016    if !na_bucket.is_empty() {
1017        groups.push((GroupKey::Na, na_bucket));
1018    }
1019    groups
1020}
1021
1022/// Logical keys: `FALSE` then `TRUE` (R's sort order), NA last.
1023/// Only keys present in the data appear.
1024fn logical_groups(column: SEXP) -> Vec<(GroupKey, Vec<usize>)> {
1025    let n = column.len() as isize;
1026    let mut false_bucket: Vec<usize> = Vec::new();
1027    let mut true_bucket: Vec<usize> = Vec::new();
1028    let mut na_bucket: Vec<usize> = Vec::new();
1029    for i in 0..n {
1030        match column.logical_elt(i) {
1031            0 => false_bucket.push(i as usize),
1032            v if v.is_na() => na_bucket.push(i as usize),
1033            _ => true_bucket.push(i as usize),
1034        }
1035    }
1036    let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(3);
1037    if !false_bucket.is_empty() {
1038        groups.push((GroupKey::Bool(false), false_bucket));
1039    }
1040    if !true_bucket.is_empty() {
1041        groups.push((GroupKey::Bool(true), true_bucket));
1042    }
1043    if !na_bucket.is_empty() {
1044        groups.push((GroupKey::Na, na_bucket));
1045    }
1046    groups
1047}
1048
1049/// Double keys (plain, `Date`, `POSIXct`, other classed doubles): numeric
1050/// sort with `NaN` after every number, `NA_real_` last. Equality follows
1051/// [`RealKey`] (`-0 == 0`, one `NaN` key); labels come from one
1052/// `as.character()` call over the distinct keys ([`real_labels`]).
1053fn real_groups(column: SEXP, col: &str) -> Result<Vec<(GroupKey, Vec<usize>)>, DataFrameError> {
1054    // SAFETY: REALSXP column; as_slice handles empty vectors.
1055    let values: &[f64] = unsafe { column.as_slice() };
1056    let mut buckets: HashMap<u64, Vec<usize>> = HashMap::new();
1057    let mut na_bucket: Vec<usize> = Vec::new();
1058    for (row, &v) in values.iter().enumerate() {
1059        if v.is_na() {
1060            na_bucket.push(row);
1061        } else {
1062            buckets
1063                .entry(normalize_real(v).to_bits())
1064                .or_default()
1065                .push(row);
1066        }
1067    }
1068    // Normalised values hold no -0.0 and one positive NaN, so `total_cmp`
1069    // gives -Inf < … < Inf < NaN, dplyr's order (NA trails separately).
1070    let mut distinct: Vec<(f64, Vec<usize>)> = buckets
1071        .into_iter()
1072        .map(|(bits, rows)| (f64::from_bits(bits), rows))
1073        .collect();
1074    distinct.sort_by(|a, b| a.0.total_cmp(&b.0));
1075
1076    let key_values: Vec<f64> = distinct.iter().map(|(value, _)| *value).collect();
1077    let labels = real_labels(column, &key_values, col)?;
1078    let mut groups: Vec<(GroupKey, Vec<usize>)> = distinct
1079        .into_iter()
1080        .zip(labels)
1081        .map(|((value, rows), label)| (GroupKey::Real(RealKey { value, label }), rows))
1082        .collect();
1083    if !na_bucket.is_empty() {
1084        groups.push((GroupKey::Na, na_bucket));
1085    }
1086    Ok(groups)
1087}
1088
1089/// R's `as.character()` of `values` carrying `column`'s attributes (class,
1090/// `tzone`, `units`, …): the text R prints for each key, with S3 dispatch for
1091/// a classed column (`Date`, `POSIXct`, …) and C-level coercion otherwise.
1092///
1093/// The temporary key vector is protected while `as.character()` allocates; a
1094/// failing method surfaces as [`DataFrameError::Conversion`] (it is evaluated
1095/// with `RCall::eval`, so it never unwinds through Rust frames).
1096fn real_labels(column: SEXP, values: &[f64], col: &str) -> Result<Vec<String>, DataFrameError> {
1097    let label_error = |detail: String| {
1098        DataFrameError::Conversion(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("cannot label the keys of column {0:?}: {1}",
                col, detail))
    })format!("cannot label the keys of column {col:?}: {detail}"))
1099    };
1100    // SAFETY: the grouping verbs run on R's main thread. `keys` is a fresh
1101    // REALSXP rooted by `OwnedProtect` until the labels are copied out.
1102    let labels = unsafe {
1103        let keys = crate::OwnedProtect::new(values.into_sexp());
1104        keys.copy_most_attrib(column);
1105        crate::convert::read_character(keys.get())
1106    }
1107    .map_err(|e| label_error(e.to_string()))?;
1108    if labels.len() != values.len() {
1109        return Err(label_error(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("as.character() returned {0} values for {1} keys",
                labels.len(), values.len()))
    })format!(
1110            "as.character() returned {} values for {} keys",
1111            labels.len(),
1112            values.len()
1113        )));
1114    }
1115    Ok(labels
1116        .into_iter()
1117        .map(|label| label.unwrap_or_else(|| "NA".to_string()))
1118        .collect())
1119}
1120// endregion
1121
1122#[cfg(test)]
1123mod tests;