Module group 

Group-level iteration over a DataFrame key column.

Two rungs, cheapest first:

1. Typed rows, grouped Rust-side — after Vec::<Row>::from_dataframe(&df)?, grouping is plain Rust. group_rows makes the idiom discoverable:

   let rows: Vec<Obs> = Vec::from_dataframe(&df)?;
   let by_site = group_rows(rows, |r| r.site.clone());
   // by_site: BTreeMap<String, Vec<Obs>> — plain Rust data, rayon-safe.

2. Untyped, index-based — DataFrame::group_by computes group indices once (single pass, main thread) without extracting rows:

   let grouped = df.group_by("site")?;
   for (key, rows) in grouped.iter() { /* key: &GroupKey, rows: &[usize] */ }
   let mut out = NamedListBuilder::with_capacity(grouped.len());
   for (key, sub) in grouped.frames() {
       // Transfer each rooted frame into the owned list.
       out.push(key.label(), sub);
   }

Key semantics (vs R split())

• Group order: factor keys follow level order (empty levels kept, like split()); character keys sort in byte order (R sorts in locale collation order — identical for ASCII); integer keys sort numerically; logical keys order FALSE, TRUE; double keys (Date and POSIXct included) sort numerically, with NaN after every number.
• NA keys form one group, ordered last — a deliberate deviation from split(), which silently drops NA-keyed rows. A literal NA level (addNA(f)) also surfaces as GroupKey::Na.
• Double keys group by value with dplyr’s (vctrs’) equality: -0 and 0 are one key, every NaN is one key, and NaN and NA are separate groups. Labels are R’s as.character() of the key — see RealKey. A bit64 integer64 column (int64 bits stored in a double vector) is an error.

Composite keys (group_by_multi)

DataFrame::group_by_multi groups on several columns at once, keying by a GroupKey::Tuple of the per-column scalar keys. Non-NA groups match split(df, interaction(col1, col2, …, drop = TRUE)) (the first column varies fastest, R interaction()’s default) — exactly, for keys whose byte order coincides with the session’s collation (always true in the C locale; single-case ASCII in practice — the character-key byte-order choice above applies per column). Extending the single-column NA convention, any tuple with an NA in any component forms its own trailing group (first-encounter order) instead of being dropped as interaction() + split() would.

Structs

GroupDeclaration

How a dplyr-grouped frame declares its grouping, returned by DataFrame::group_declaration: the grouping variables and the .drop policy, without the cached group rows.

GroupedDataFrame

A DataFrame partitioned by the values of one key column.

GroupsAttr 🔒

A grouped frame’s groups attribute after the structural checks of DataFrame::groups_attr.

RealKey

The key of one double-valued group (GroupKey::Real): the value plus the text R prints for it.

Enums

GroupKey

The key of one group produced by DataFrame::group_by or DataFrame::group_by_multi.

Constants

CANONICAL_NAN_BITS 🔒

Bits of the one NaN every NaN key is stored as: positive and quiet, so f64::total_cmp orders it after +Inf on every platform (x86’s 0/0 has the sign bit set), and its low word is not R’s NA payload (1954).

Functions

character_groups 🔒

Character keys: byte-order sort (BTreeMap), NA last.

check_rows_partition 🔒

Check that in-range .rows cover each of the frame’s nrow rows exactly once — the shape dplyr always maintains. The first row claimed twice, or else the first row no group claims, is reported.

column_groups 🔒

One supported key column’s groups, in single-column group order (NA last) — the per-type dispatch behind DataFrame::group_by, and through column_keys / row_keys behind group_by_multi and group_by_metadata.

column_keys 🔒

Per-row group key for one supported key column, in row order. NA cells — and factor NA codes / addNA() levels — become GroupKey::Na. Same type dispatch and errors as DataFrame::group_by.

factor_groups 🔒

Factor fast path: levels are the keys (level order, empty levels kept). NA codes — and a literal NA level from addNA() — land in GroupKey::Na.

group_rows

Group already-extracted rows by a key function.

group_rows_indices 🔒

Convert one .rows list element — an integer vector of 1-based row indices (DataFrame::groups_attr checked its type) — into 0-based indices, rejecting any index outside 1..=nrow (NA included).

integer_groups 🔒

Integer keys: numeric sort (BTreeMap), NA (i32::MIN) last.

logical_groups 🔒

Logical keys: FALSE then TRUE (R’s sort order), NA last. Only keys present in the data appear.

normalize_real 🔒

Map a non-NA double to its key representative: -0.0 → 0.0, any NaN → the canonical NaN. Equal keys (by vctrs’ rules) then share their bits.

r_typeof 🔒

R’s typeof() of x: "double", "NULL", "list", ….

real_groups 🔒

Double keys (plain, Date, POSIXct, other classed doubles): numeric sort with NaN after every number, NA_real_ last. Equality follows RealKey (-0 == 0, one NaN key); labels come from one as.character() call over the distinct keys (real_labels).

real_labels 🔒

R’s as.character() of values carrying column’s attributes (class, tzone, units, …): the text R prints for each key, with S3 dispatch for a classed column (Date, POSIXct, …) and C-level coercion otherwise.

row_keys 🔒

Invert groups into one key per row (nrow rows, row order). Each row of a key column lands in exactly one group, so every slot is filled.