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.
5556use std::collections::{BTreeMap, HashMap};
5758use super::{DataFrame, DataFrameError, FromDataFrame};
59use crate::into_r::IntoR;
60use crate::{IsNA, SEXP, SEXPTYPE, SexpExt};
6162// region: group_rows — typed-rows grouping helper (rung 1)
6364/// 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
71K: Ord,
72 F: Fn(&T) -> K,
73{
74let mut groups: BTreeMap<K, Vec<T>> = BTreeMap::new();
75for row in rows {
76 groups.entry(key(&row)).or_default().push(row);
77 }
78groups79}
80// endregion
8182// region: GroupKey
8384/// 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.
89Str(String),
90/// An integer key.
91Int(i32),
92/// A double key: a plain number, a `Date`, a `POSIXct`, or another classed
93 /// double. See [`RealKey`] for its equality and label.
94Real(RealKey),
95/// A logical key.
96Bool(bool),
97/// The NA-keyed group (always ordered last).
98Na,
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)).
103Tuple(Vec<GroupKey>),
104}
105106impl 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.
112pub fn label(&self) -> String {
113match 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) => {
121if 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);
125keys.iter()
126 .map(GroupKey::label)
127 .collect::<Vec<_>>()
128 .join(".")
129 }
130 }
131 }
132}
133134impl std::fmt::Displayfor GroupKey {
135fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
136match 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) => {
144for (i, key) in keys.iter().enumerate() {
145if i > 0 {
146 f.write_str(".")?;
147 }
148f.write_fmt(format_args!("{0}", key))write!(f, "{}", key)?;
149 }
150Ok(())
151 }
152 }
153 }
154}
155156/// 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}
180181impl 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.
184pub fn new(value: f64, label: impl Into<String>) -> Self {
185RealKey {
186 value: normalize_real(value),
187 label: label.into(),
188 }
189 }
190191/// 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.
194pub fn value(&self) -> f64 {
195self.value
196 }
197198/// The text R prints for the key (see the [type docs](Self)).
199pub fn label(&self) -> &str {
200&self.label
201 }
202}
203204impl PartialEqfor RealKey {
205fn eq(&self, other: &Self) -> bool {
206self.value.to_bits() == other.value.to_bits()
207 }
208}
209210impl Eqfor RealKey {}
211212impl std::hash::Hashfor RealKey {
213fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
214self.value.to_bits().hash(state);
215 }
216}
217218/// 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;
222223/// 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 {
226if x == 0.0 {
2270.0
228} else if x.is_nan() {
229f64::from_bits(CANONICAL_NAN_BITS)
230 } else {
231x232 }
233}
234// endregion
235236// region: GroupDeclaration
237238/// 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.
247pub 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`.
255pub drop: bool,
256}
257258/// 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.
263frame: SEXP,
264/// Its last column, `.rows`: a list of integer vectors, one per group.
265rows: SEXP,
266}
267268impl 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.
275fn key_columns(&self) -> Result<Vec<(String, SEXP)>, DataFrameError> {
276let names = self.frame.get_names();
277let mut columns: Vec<(String, SEXP)> = Vec::new();
278let mut errors = crate::from_r::BatchedErrors::default();
279for i in 0..self.frame.len() {
280let charsxp = names.string_elt(i as isize);
281let name = if charsxp.is_na_string() {
282""
283} else {
284match text_key(charsxp, i, "", &mut errors) {
285Some(name) => name,
286None => continue,
287 }
288 };
289if name == ".rows" || columns.iter().any(|(seen, _)| seen == name) {
290continue;
291 }
292 columns.push((name.to_string(), self.frame.vector_elt(i as isize)));
293 }
294if !errors.is_empty() {
295return 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 }
300Ok(columns)
301 }
302}
303// endregion
304305// region: GroupedDataFrame
306307/// 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}
327328impl Dropfor GroupedDataFrame {
329fn drop(&mut self) {
330// SAFETY: main thread (construction invariant — SEXP is !Send);
331 // releases the preserve taken in `group_by`.
332unsafe { crate::sys::R_ReleaseObject(self.source.as_sexp()) };
333 }
334}
335336impl 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`.
341fn new(source: DataFrame, groups: Vec<(GroupKey, Vec<usize>)>) -> Self {
342unsafe {
343let _guard = crate::OwnedProtect::new(source.sexp);
344crate::sys::R_PreserveObject(source.sexp);
345 }
346GroupedDataFrame { source, groups }
347 }
348349/// Number of groups (empty factor levels included).
350pub fn len(&self) -> usize {
351self.groups.len()
352 }
353354/// Whether there are no groups.
355pub fn is_empty(&self) -> bool {
356self.groups.is_empty()
357 }
358359/// The frame this grouping was computed from.
360pub fn source(&self) -> &DataFrame {
361&self.source
362 }
363364/// Iterate `(key, row-indices)` pairs in group order. Indices are 0-based
365 /// rows of [`source`](Self::source).
366pub fn iter(&self) -> impl Iterator<Item = (&GroupKey, &[usize])> {
367self.groups.iter().map(|(k, idx)| (k, idx.as_slice()))
368 }
369370/// 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.
378pub fn frames(&self) -> impl Iterator<Item = (&GroupKey, crate::dataframe::BuiltDataFrame)> {
379self.groups
380 .iter()
381 .map(|(k, idx)| (k, self.source.select_rows(idx)))
382 }
383384/// 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).
389pub fn extract<T>(&self) -> Result<Vec<(GroupKey, Vec<T>)>, DataFrameError>
390where
391Vec<T>: FromDataFrame,
392 {
393let rows = Vec::<T>::from_dataframe(&self.source)?;
394let mut slots: Vec<Option<T>> = rows.into_iter().map(Some).collect();
395Ok(self396 .groups
397 .iter()
398 .map(|(key, idx)| {
399let group_rows: Vec<T> = idx400 .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
409410// region: DataFrame::group_by
411412impl 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.
424pub fn group_by(&self, col: &str) -> Result<GroupedDataFrame, DataFrameError> {
425let column = self
426.column_raw(col)
427 .ok_or_else(|| DataFrameError::NoSuchColumn(col.to_string()))?;
428let groups = column_groups(column, col)?;
429// Root the source for the GroupedDataFrame's lifetime (see its GC
430 // rooting docs).
431Ok(GroupedDataFrame::new(*self, groups))
432 }
433434/// 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.
469pub fn group_by_multi(&self, cols: &[&str]) -> Result<GroupedDataFrame, DataFrameError> {
470if cols.is_empty() {
471return Err(DataFrameError::EmptyGroupColumns);
472 }
473// A single column is the scalar path — identical keys/order to group_by.
474if let [col] = cols {
475return self.group_by(col);
476 }
477478// 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.
482let mut per_row: Vec<Vec<GroupKey>> = Vec::with_capacity(cols.len());
483let mut ordinals: Vec<HashMap<GroupKey, usize>> = Vec::with_capacity(cols.len());
484for &col in cols {
485let column = self
486.column_raw(col)
487 .ok_or_else(|| DataFrameError::NoSuchColumn(col.to_string()))?;
488let 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 }
500501// Bucket rows into tuple keys, preserving first-encounter order.
502let mut index: HashMap<GroupKey, usize> = HashMap::new();
503let mut buckets: Vec<(GroupKey, Vec<usize>)> = Vec::new();
504for (row, first) in per_row[0].iter().enumerate() {
505let mut elems = Vec::with_capacity(cols.len());
506 elems.push(first.clone());
507for col in &per_row[1..] {
508 elems.push(col[row].clone());
509 }
510let key = GroupKey::Tuple(elems);
511match index.get(&key) {
512Some(&pos) => buckets[pos].1.push(row),
513None => {
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 }
519520// 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).
523let 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)));
524let (mut non_na, na_tuples): (Vec<_>, Vec<_>) =
525buckets.into_iter().partition(|(k, _)| !is_na_tuple(k));
526non_na.sort_by_key(|(k, _)| {
527let GroupKey::Tuple(elems) = kelse {
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 };
530let mut ord: Vec<usize> = elems531 .iter()
532 .enumerate()
533 .map(|(c, e)| ordinals[c][e])
534 .collect();
535ord.reverse();
536ord537 });
538non_na.extend(na_tuples);
539540Ok(GroupedDataFrame::new(*self, non_na))
541 }
542543/// 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 /// ```
594pub fn group_declaration(&self) -> Result<Option<GroupDeclaration>, DataFrameError> {
595let Some(groups) = self.groups_attr()? else {
596return 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.
603let drop = !self.sexp.inherits_class(c"grouped_df") || {
604let drop_attr = groups605 .frame
606 .get_attr(unsafe { crate::sys::Rf_install(c".drop".as_ptr()) });
607unsafe {
608crate::sys::R_compute_identical(
609drop_attr,
610crate::sys::Rf_ScalarLogical(0),
611crate::sys::IDENT_USE_CLOENV,
612 ) == crate::sexp_types::Rboolean::FALSE613 }
614 };
615Ok(Some(GroupDeclaration {
616 vars: groups
617 .key_columns()?
618.into_iter()
619 .map(|(name, _)| name)
620 .collect(),
621drop,
622 }))
623 }
624625/// 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).
703pub fn group_by_metadata(&self) -> Result<GroupedDataFrame, DataFrameError> {
704let attr = self
705.groups_attr()?
706.ok_or(DataFrameError::NotGroupedDataFrame)?;
707let n_groups = attr.rows.len();
708let key_columns = attr.key_columns()?;
709710// 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).
712let mut per_col_keys: Vec<Vec<GroupKey>> = Vec::with_capacity(key_columns.len());
713for (name, column) in &key_columns {
714let keys = column_keys(*column, name)?;
715if keys.len() != n_groups {
716return 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 }
723724let nrow = self.nrow();
725let single_key = key_columns.len() == 1;
726727let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(n_groups);
728for 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).
731let 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.
737let elt = attr.rows.vector_elt(g as isize);
738let 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.
742check_rows_partition(&groups, nrow)?;
743744Ok(GroupedDataFrame::new(*self, groups))
745 }
746747/// 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.
761fn groups_attr(&self) -> Result<Option<GroupsAttr>, DataFrameError> {
762if !(self.sexp.inherits_class(c"grouped_df") || self.sexp.inherits_class(c"rowwise_df")) {
763return Ok(None);
764 }
765let groups_sym = unsafe { crate::sys::Rf_install(c"groups".as_ptr()) };
766let frame = self.sexp.get_attr(groups_sym);
767// dplyr reads the columns with VECTOR_ELT, so the frame must be a list.
768if frame.type_of() != SEXPTYPE::VECSXP || !frame.is_data_frame() || frame.len() == 0 {
769return Err(DataFrameError::GroupsNotDataFrame);
770 }
771let names = frame.get_names();
772let last_is_rows = names.type_of() == SEXPTYPE::STRSXP773 && names.len() == frame.len()
774 && crate::list::text_name(names.string_elt(names.len() as isize - 1)) == Some(".rows");
775if !last_is_rows {
776return Err(DataFrameError::MissingGroupRows);
777 }
778let rows = frame.vector_elt(frame.len() as isize - 1);
779if rows.type_of() != SEXPTYPE::VECSXP {
780return Err(DataFrameError::BadGroupRows {
781 group: None,
782 type_of: r_typeof(rows),
783 });
784 }
785for group in 0..rows.len() {
786let elt = rows.vector_elt(group as isize);
787if elt.type_of() != SEXPTYPE::INTSXP {
788return Err(DataFrameError::BadGroupRows {
789 group: Some(group),
790 type_of: r_typeof(elt),
791 });
792 }
793 }
794Ok(Some(GroupsAttr { frame, rows }))
795 }
796}
797798/// 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.
801unsafe { std::ffi::CStr::from_ptr(crate::sys::Rf_type2char(x.type_of())) }
802 .to_string_lossy()
803 .into_owned()
804}
805806/// 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.
812let values: &[i32] = unsafe { elt.as_slice() };
813values814 .iter()
815 .map(|&value| match usize::try_from(value) {
816Ok(row) if (1..=nrow).contains(&row) => Ok(row - 1),
817_ => Err(DataFrameError::GroupIndexOutOfRange {
818group,
819 value: i64::from(value),
820nrow,
821 }),
822 })
823 .collect()
824}
825826/// 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> {
833let mut owner: Vec<Option<usize>> = ::alloc::vec::from_elem_global(None, nrow)vec![None; nrow];
834for (group, (_, rows)) in groups.iter().enumerate() {
835for &row in rows {
836if let Some(first_group) = owner[row] {
837return Err(DataFrameError::GroupRowDuplicated {
838 row,
839 first_group,
840 second_group: group,
841 });
842 }
843 owner[row] = Some(group);
844 }
845 }
846match owner.iter().position(Option::is_none) {
847Some(row) => Err(DataFrameError::GroupRowUncovered { row, nrow }),
848None => Ok(()),
849 }
850}
851852/// 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> {
857if column.is_factor() {
858return factor_groups(column, col);
859 }
860let unsupported = |type_of: String| DataFrameError::UnsupportedGroupColumn {
861 column: col.to_string(),
862type_of,
863 };
864match 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.
871SEXPTYPE::REALSXPif column.inherits_class(c"integer64") => {
872Err(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}
878879/// 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> {
882let mut keys: Vec<Option<GroupKey>> = ::alloc::vec::from_elem_global(None, nrow)vec![None; nrow];
883for (key, rows) in groups {
884for &row in rows {
885 keys[row] = Some(key.clone());
886 }
887 }
888keys.into_iter()
889 .map(|key| key.expect("each row of a key column is in exactly one group"))
890 .collect()
891}
892893/// 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> {
897Ok(row_keys(&column_groups(column, col)?, column.len()))
898}
899900/// 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.
912unsafe { 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}
916917/// 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}
925926/// 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.
931let codes: &[i32] = unsafe { column.as_slice() };
932let levels = column.get_levels();
933let n_levels: usize = if levels.is_nil() { 0 } else { levels.len() };
934935let mut buckets: Vec<Vec<usize>> = ::alloc::vec::from_elem_global(Vec::new(), n_levels)vec![Vec::new(); n_levels];
936let mut na_bucket: Vec<usize> = Vec::new();
937for (row, &code) in codes.iter().enumerate() {
938if code.is_na() {
939 na_bucket.push(row);
940 } else {
941 buckets[(code - 1) as usize].push(row);
942 }
943 }
944945let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(n_levels + 1);
946let mut errors = crate::from_r::BatchedErrors::default();
947for (lvl, bucket) in buckets.into_iter().enumerate() {
948let level = levels.string_elt(lvl as isize);
949let key = if level.is_na_string() {
950 GroupKey::Na // addNA() level
951} else {
952match text_key(level, lvl, "level ", &mut errors) {
953Some(label) => GroupKey::Str(label.to_string()),
954None => continue,
955 }
956 };
957 groups.push((key, bucket));
958 }
959if !errors.is_empty() {
960return Err(keys_not_text(col, errors));
961 }
962if !na_bucket.is_empty() {
963groups.push((GroupKey::Na, na_bucket));
964 }
965Ok(groups)
966}
967968/// 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> {
974let n = column.len();
975let mut map: BTreeMap<String, Vec<usize>> = BTreeMap::new();
976let mut na_bucket: Vec<usize> = Vec::new();
977let mut errors = crate::from_r::BatchedErrors::default();
978for i in 0..n {
979let charsxp = column.string_elt(i as isize);
980if 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 }
986if !errors.is_empty() {
987return Err(keys_not_text(col, errors));
988 }
989let mut groups: Vec<(GroupKey, Vec<usize>)> = map990 .into_iter()
991 .map(|(k, idx)| (GroupKey::Str(k), idx))
992 .collect();
993if !na_bucket.is_empty() {
994groups.push((GroupKey::Na, na_bucket));
995 }
996Ok(groups)
997}
998999/// 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.
1002let values: &[i32] = unsafe { column.as_slice() };
1003let mut map: BTreeMap<i32, Vec<usize>> = BTreeMap::new();
1004let mut na_bucket: Vec<usize> = Vec::new();
1005for (row, &v) in values.iter().enumerate() {
1006if v.is_na() {
1007 na_bucket.push(row);
1008 } else {
1009 map.entry(v).or_default().push(row);
1010 }
1011 }
1012let mut groups: Vec<(GroupKey, Vec<usize>)> = map1013 .into_iter()
1014 .map(|(k, idx)| (GroupKey::Int(k), idx))
1015 .collect();
1016if !na_bucket.is_empty() {
1017groups.push((GroupKey::Na, na_bucket));
1018 }
1019groups1020}
10211022/// 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>)> {
1025let n = column.len() as isize;
1026let mut false_bucket: Vec<usize> = Vec::new();
1027let mut true_bucket: Vec<usize> = Vec::new();
1028let mut na_bucket: Vec<usize> = Vec::new();
1029for i in 0..n {
1030match column.logical_elt(i) {
10310 => 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 }
1036let mut groups: Vec<(GroupKey, Vec<usize>)> = Vec::with_capacity(3);
1037if !false_bucket.is_empty() {
1038groups.push((GroupKey::Bool(false), false_bucket));
1039 }
1040if !true_bucket.is_empty() {
1041groups.push((GroupKey::Bool(true), true_bucket));
1042 }
1043if !na_bucket.is_empty() {
1044groups.push((GroupKey::Na, na_bucket));
1045 }
1046groups1047}
10481049/// 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.
1055let values: &[f64] = unsafe { column.as_slice() };
1056let mut buckets: HashMap<u64, Vec<usize>> = HashMap::new();
1057let mut na_bucket: Vec<usize> = Vec::new();
1058for (row, &v) in values.iter().enumerate() {
1059if 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).
1070let mut distinct: Vec<(f64, Vec<usize>)> = buckets1071 .into_iter()
1072 .map(|(bits, rows)| (f64::from_bits(bits), rows))
1073 .collect();
1074distinct.sort_by(|a, b| a.0.total_cmp(&b.0));
10751076let key_values: Vec<f64> = distinct.iter().map(|(value, _)| *value).collect();
1077let labels = real_labels(column, &key_values, col)?;
1078let mut groups: Vec<(GroupKey, Vec<usize>)> = distinct1079 .into_iter()
1080 .zip(labels)
1081 .map(|((value, rows), label)| (GroupKey::Real(RealKey { value, label }), rows))
1082 .collect();
1083if !na_bucket.is_empty() {
1084groups.push((GroupKey::Na, na_bucket));
1085 }
1086Ok(groups)
1087}
10881089/// 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> {
1097let 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.
1102let labels = unsafe {
1103let keys = crate::OwnedProtect::new(values.into_sexp());
1104 keys.copy_most_attrib(column);
1105crate::convert::read_character(keys.get())
1106 }
1107 .map_err(|e| label_error(e.to_string()))?;
1108if labels.len() != values.len() {
1109return 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 }
1115Ok(labels1116 .into_iter()
1117 .map(|label| label.unwrap_or_else(|| "NA".to_string()))
1118 .collect())
1119}
1120// endregion
11211122#[cfg(test)]
1123mod tests;