miniextendr_api/dataframe.rs
1//! R `data.frame` views, rooted Rust-built handles, and conversion traits.
2//!
3//! [`DataFrame`] is a cheap `Copy` view over a validated `data.frame` SEXP;
4//! [`BuiltDataFrame`] is the owned, GC-rooted handle returned by every
5//! Rust-side constructor. Together they serve every direction:
6//!
7//! - **build** (Rust → R): [`IntoDataFrame::into_dataframe`] / `into_dataframe_par` (`feature = "rayon"`),
8//! - **read** (R → Rust): [`DataFrame::column`] / [`FromDataFrame::from_dataframe`],
9//! - **edit** (post-assembly): [`DataFrame::rename`] / [`DataFrame::drop`] / [`DataFrame::select`] / …
10//! — the new-frame producers return an owned, GC-rooted [`BuiltDataFrame`] (#1247),
11//! so constructor → edit chains stay rooted at every link.
12//!
13//! The trait family mirrors the crate's existing [`IntoR`] /
14//! [`TryFromSexp`] pair, specialised to the data-frame SEXP:
15//!
16//! ```ignore
17//! use miniextendr_api::dataframe::{DataFrame, IntoDataFrame, FromDataFrame};
18//!
19//! // Rust → R (returns an owned, GC-rooted `BuiltDataFrame` that `Deref`s to `DataFrame`)
20//! let df = rows.into_dataframe()?; // sequential
21//! let df = rows.into_dataframe_par()?; // parallel (feature = "rayon")
22//!
23//! // R → Rust
24//! let rows: Vec<Row> = Vec::<Row>::from_dataframe(&df)?;
25//! ```
26//!
27//! `DataFrame` implements `TryFromSexp` and `IntoR`, so caller-rooted views slot
28//! into `#[miniextendr]` argument and return conversion. `BuiltDataFrame` also
29//! implements `IntoR`; return rooted Rust-side constructor results directly.
30//!
31//! # One error contract
32//!
33//! Every conversion failure surfaces as [`DataFrameError`]. The serde column assembler's
34//! internal `RSerdeError` is bridged via `From<RSerdeError>`; the parallel R→Rust reader
35//! reports through `DataFrameError` rather than a bare `String`.
36
37use crate::from_r::{SexpClassError, SexpError, TryFromSexp};
38use crate::into_r::IntoR;
39use crate::list::{List, NamedList};
40use crate::typed_list::{TypedList, TypedListError, TypedListSpec, validate_list};
41use crate::{IsNA, SEXP, SEXPTYPE, SexpExt};
42
43pub mod group;
44pub use group::{GroupDeclaration, GroupKey, GroupedDataFrame, RealKey, group_rows};
45
46mod shape;
47pub use shape::{DataFrameShape, SplitResults};
48
49mod borrowed;
50#[doc(hidden)]
51pub use borrowed::{DataFrameRowBorrow, StringColumn};
52
53// region: Error type
54
55/// Error returned by any [`DataFrame`] construction, read, or conversion path.
56///
57/// This is the single data-frame error contract: the row-buffer build path, the serde
58/// columnar path, the parallel R→Rust reader, and validation all surface a `DataFrameError`.
59#[derive(Debug, Clone)]
60pub enum DataFrameError {
61 /// The SEXP is not a VECSXP; carries the SEXPTYPE it was.
62 NotList(SEXPTYPE),
63 /// The object does not inherit from `data.frame`.
64 NotDataFrame,
65 /// The list has no `names` attribute (columns must be named).
66 NoNames,
67 /// Could not extract `nrow` from `row.names` attribute.
68 BadRowNames(String),
69 /// Columns have unequal lengths (when promoting from a named list).
70 UnequalLengths {
71 /// First column length encountered.
72 expected: usize,
73 /// Every mismatched column, in order, with its actual length.
74 columns: Vec<(String, usize)>,
75 },
76 /// A row could not be turned into named columns (e.g. unnamed list elements
77 /// in a `IntoList`-derived row). Replaces the old `panic!` on this path.
78 UnnamedColumns,
79 /// [`DataFrame::group_by`] referenced a column name that does not exist.
80 NoSuchColumn(String),
81 /// [`DataFrame::group_by_multi`] was called with an empty column slice.
82 EmptyGroupColumns,
83 /// [`DataFrame::group_by`] on a column type with no grouping semantics
84 /// (list-columns, complex, raw, bit64 `integer64`, …).
85 UnsupportedGroupColumn {
86 /// The offending column name.
87 column: String,
88 /// Its SEXPTYPE (or `"integer64"`), rendered for the message.
89 type_of: String,
90 },
91 /// [`DataFrame::group_by_metadata`] was called on a frame that does not
92 /// inherit from `grouped_df` or `rowwise_df`.
93 NotGroupedDataFrame,
94 /// A frame inherits from `grouped_df` or `rowwise_df`, but its `groups`
95 /// attribute is missing or is not a data frame with at least one column.
96 /// dplyr treats such a frame as corrupt, not as ungrouped ("The `groups`
97 /// attribute must be a data frame.").
98 GroupsNotDataFrame,
99 /// The last column of a grouped frame's `groups` attribute is not called
100 /// `.rows` (dplyr: "The last column of the `groups` attribute must be
101 /// called `.rows`.").
102 MissingGroupRows,
103 /// The `.rows` column of a grouped frame's `groups` attribute is not a
104 /// list of integer vectors (dplyr: "The `.rows` column must be list of
105 /// one-based integer vectors."). Doubles are rejected, as in dplyr.
106 BadGroupRows {
107 /// The 0-based group (row of the `groups` frame) whose element is not
108 /// an integer vector, or `None` when the `.rows` column itself is not
109 /// a list. The message numbers groups from 1, as R does.
110 group: Option<usize>,
111 /// R's `typeof()` of the offending element (or of the `.rows`
112 /// column), rendered for the message.
113 type_of: String,
114 },
115 /// A `.rows` index was `< 1` or `> nrow` of the source frame: the
116 /// grouping metadata is stale. The message names the usual cause (the
117 /// frame was subset without dplyr loaded) and the fix.
118 GroupIndexOutOfRange {
119 /// The 0-based group whose `.rows` carried the bad index; the message
120 /// numbers it from 1, as R does.
121 group: usize,
122 /// The offending 1-based index value.
123 value: i64,
124 /// The source frame's row count (valid indices are `1..=nrow`).
125 nrow: usize,
126 },
127 /// No group's `.rows` holds this row of the source frame: the grouping
128 /// metadata is stale (the message names the cause and the fix).
129 GroupRowUncovered {
130 /// The first uncovered 0-based row; the message numbers it from 1.
131 row: usize,
132 /// The source frame's row count.
133 nrow: usize,
134 },
135 /// Two `.rows` entries hold the same row of the source frame (in two
136 /// groups, or twice in one): the grouping metadata is stale (the message
137 /// names the cause and the fix).
138 GroupRowDuplicated {
139 /// The 0-based row; the message numbers it from 1.
140 row: usize,
141 /// The 0-based group that held the row first.
142 first_group: usize,
143 /// The 0-based group that held it again (equal to `first_group` for a
144 /// row listed twice in one group).
145 second_group: usize,
146 },
147 /// A serde-driven schema/serialize/deserialize failure (the bridged
148 /// `RSerdeError` text) or another conversion failure carried as a message.
149 Conversion(String),
150}
151
152impl std::fmt::Display for DataFrameError {
153 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
154 match self {
155 DataFrameError::NotList(actual) => write!(
156 f,
157 "expected a data frame, got {}",
158 crate::typed_list::sexptype_name(*actual)
159 ),
160 DataFrameError::NotDataFrame => write!(f, "object does not inherit from data.frame"),
161 DataFrameError::NoNames => write!(f, "data.frame has no column names"),
162 DataFrameError::BadRowNames(msg) => {
163 write!(f, "could not extract nrow from row.names: {}", msg)
164 }
165 DataFrameError::UnequalLengths { expected, columns } => {
166 for (i, (column, actual)) in columns.iter().enumerate() {
167 if i > 0 {
168 write!(f, "; ")?;
169 }
170 write!(
171 f,
172 "column {column:?} has length {actual} (expected {expected})"
173 )?;
174 }
175 Ok(())
176 }
177 DataFrameError::UnnamedColumns => {
178 write!(f, "cannot create data frame from unnamed list elements")
179 }
180 DataFrameError::NoSuchColumn(name) => {
181 write!(f, "no such column: {:?}", name)
182 }
183 DataFrameError::EmptyGroupColumns => {
184 write!(f, "group_by_multi requires at least one column")
185 }
186 DataFrameError::UnsupportedGroupColumn { column, type_of } => write!(
187 f,
188 "cannot group by column {:?} ({}): supported key types are factor, \
189 character, integer, logical, and double (including Date and POSIXct)",
190 column, type_of
191 ),
192 DataFrameError::NotGroupedDataFrame => write!(
193 f,
194 "not a grouped_df: the frame does not inherit from grouped_df or rowwise_df; \
195 use group_by/group_by_multi to compute grouping instead"
196 ),
197 DataFrameError::GroupsNotDataFrame => write!(
198 f,
199 "not a valid grouped_df or rowwise_df: the `groups` attribute must be a data \
200 frame. {}",
201 CORRUPT_GROUPS_HINT
202 ),
203 DataFrameError::MissingGroupRows => write!(
204 f,
205 "not a valid grouped_df or rowwise_df: the last column of the `groups` \
206 attribute must be called `.rows`. {}",
207 CORRUPT_GROUPS_HINT
208 ),
209 DataFrameError::BadGroupRows {
210 group: None,
211 type_of,
212 } => write!(
213 f,
214 "not a valid grouped_df or rowwise_df: the `.rows` column must be a list of \
215 one-based integer vectors, not {}. {}",
216 type_of, CORRUPT_GROUPS_HINT
217 ),
218 DataFrameError::BadGroupRows {
219 group: Some(group),
220 type_of,
221 } => write!(
222 f,
223 "not a valid grouped_df or rowwise_df: the `.rows` column must be a list of \
224 one-based integer vectors, but the element for group {} is {}. {}",
225 group + 1,
226 type_of,
227 CORRUPT_GROUPS_HINT
228 ),
229 DataFrameError::GroupIndexOutOfRange { group, value, nrow } => write!(
230 f,
231 "grouped_df `.rows` index {} for group {} is out of range (the frame has \
232 {} rows; valid indices are 1..={}). {}",
233 value,
234 group + 1,
235 nrow,
236 nrow,
237 STALE_GROUPS_HINT
238 ),
239 DataFrameError::GroupRowUncovered { row, nrow } => write!(
240 f,
241 "grouped_df `.rows` do not cover row {} (the frame has {} rows; each row \
242 belongs to exactly one group). {}",
243 row + 1,
244 nrow,
245 STALE_GROUPS_HINT
246 ),
247 DataFrameError::GroupRowDuplicated {
248 row,
249 first_group,
250 second_group,
251 } if first_group == second_group => write!(
252 f,
253 "grouped_df `.rows` list row {} twice in group {} (each row belongs to \
254 exactly one group). {}",
255 row + 1,
256 first_group + 1,
257 STALE_GROUPS_HINT
258 ),
259 DataFrameError::GroupRowDuplicated {
260 row,
261 first_group,
262 second_group,
263 } => write!(
264 f,
265 "grouped_df `.rows` put row {} in both group {} and group {} (each row \
266 belongs to exactly one group). {}",
267 row + 1,
268 first_group + 1,
269 second_group + 1,
270 STALE_GROUPS_HINT
271 ),
272 DataFrameError::Conversion(msg) => write!(f, "{}", msg),
273 }
274 }
275}
276
277impl std::error::Error for DataFrameError {}
278
279/// The condition a `DataFrameError` raises in R: its message, no class or
280/// fields. It is [`AsDataFrame`](crate::convert::AsDataFrame)'s
281/// `IntoR::Error`.
282impl crate::condition::RConditionData for DataFrameError {
283 fn message(&self) -> String {
284 self.to_string()
285 }
286}
287
288/// The cause and the fix that the stale-`.rows` errors
289/// ([`DataFrameError::GroupIndexOutOfRange`],
290/// [`DataFrameError::GroupRowUncovered`],
291/// [`DataFrameError::GroupRowDuplicated`]) append to their message.
292const STALE_GROUPS_HINT: &str = "The `groups` metadata is stale: the grouped frame was \
293 likely subset or reordered without dplyr loaded, which keeps the old `groups` attribute. \
294 Regroup it with dplyr::group_by() (with dplyr loaded, `[` regroups by itself), or read just \
295 the grouping declaration (DataFrame::group_declaration) and group the current rows.";
296
297/// The fix that the corrupt-`groups` errors ([`DataFrameError::GroupsNotDataFrame`],
298/// [`DataFrameError::MissingGroupRows`], [`DataFrameError::BadGroupRows`])
299/// append to their message.
300const CORRUPT_GROUPS_HINT: &str = "dplyr's validators reject such a frame too. Strip the \
301 grouping with dplyr::ungroup(), then regroup it with dplyr::group_by().";
302
303#[cfg(feature = "serde")]
304impl From<crate::serde::RSerdeError> for DataFrameError {
305 fn from(e: crate::serde::RSerdeError) -> Self {
306 DataFrameError::Conversion(e.to_string())
307 }
308}
309// endregion
310
311// region: DataFrame — cheap, unrooted data.frame view
312
313/// A cheap `Copy` view over a validated R `data.frame`.
314///
315/// The view carries no GC root. It is sound while an R `.Call` argument frame,
316/// a [`ProtectScope`](crate::ProtectScope), or an owning [`BuiltDataFrame`]
317/// keeps the SEXP reachable. Rust-side constructors never return this bare
318/// view; they return `BuiltDataFrame`.
319///
320/// # Building
321///
322/// Prefer the [`IntoDataFrame`] trait on your data (it returns an owned,
323/// GC-rooted [`BuiltDataFrame`] that `Deref`s to `DataFrame`):
324///
325/// ```ignore
326/// let df = rows.into_dataframe()?;
327/// ```
328///
329/// or the closure-fill `DataFrame::builder` for heterogeneous parallel column fill
330/// (`feature = "rayon"`).
331///
332/// # Reading
333///
334/// Wrap an incoming SEXP with [`DataFrame::from_sexp`] (or accept `DataFrame` directly as a
335/// `#[miniextendr]` argument), then pull typed columns with [`DataFrame::column`], or
336/// deserialize whole rows with [`FromDataFrame`].
337#[derive(Clone, Copy)]
338pub struct DataFrame {
339 sexp: SEXP,
340}
341
342impl DataFrame {
343 /// Wrap an already-built `data.frame` SEXP without re-validation.
344 ///
345 /// Used by the column assemblers, which produce a well-formed `data.frame` by
346 /// construction.
347 ///
348 /// # Safety
349 ///
350 /// `sexp` must be a VECSXP with the `data.frame` class and consistent `row.names`.
351 #[inline]
352 pub unsafe fn from_built_sexp(sexp: SEXP) -> Self {
353 Self { sexp }
354 }
355
356 /// Wrap an existing R `data.frame` SEXP, validating it.
357 ///
358 /// Validates that the object:
359 /// 1. Is a VECSXP (list)
360 /// 2. Inherits from `"data.frame"`
361 /// 3. Has a `names` attribute
362 /// 4. Has extractable `row.names` for nrow
363 ///
364 /// # Errors
365 ///
366 /// Returns [`DataFrameError`] if validation fails.
367 pub fn from_sexp(sexp: SEXP) -> Result<Self, DataFrameError> {
368 let stype = sexp.type_of();
369 if stype != SEXPTYPE::VECSXP {
370 return Err(DataFrameError::NotList(stype));
371 }
372 if !sexp.is_data_frame() {
373 return Err(DataFrameError::NotDataFrame);
374 }
375 // Require a names attribute (columns must be named).
376 let list = unsafe { List::from_raw(sexp) };
377 NamedList::new(list).ok_or(DataFrameError::NoNames)?;
378 // Confirm nrow is extractable.
379 extract_nrow(sexp)?;
380 Ok(Self { sexp })
381 }
382
383 // region: Read API (R → Rust column / row access)
384
385 /// Get a column by name, converting to type `T`.
386 ///
387 /// Returns `None` if the column name is not found or conversion fails.
388 ///
389 /// `T` may be a vector/collection target (`Vec<f64>`, `Vec<i32>`,
390 /// `Vec<String>`, …) — the natural shape for a column — or a scalar for a
391 /// length-1 column. The conversion error is discarded (that is what makes
392 /// this return `Option`), so `T::Error` is unconstrained; use
393 /// [`column_raw`](Self::column_raw) when you need the error.
394 #[inline]
395 pub fn column<T>(&self, name: &str) -> Option<T>
396 where
397 T: TryFromSexp,
398 {
399 self.named_list().get(name)
400 }
401
402 /// Get a column by 0-based index, converting to type `T`.
403 ///
404 /// As with [`column`](Self::column), `T` may be a vector/collection or a
405 /// scalar target type; the conversion error is discarded.
406 #[inline]
407 pub fn column_index<T>(&self, idx: usize) -> Option<T>
408 where
409 T: TryFromSexp,
410 {
411 let idx_isize: isize = idx.try_into().ok()?;
412 self.named_list().get_index(idx_isize)
413 }
414
415 /// Get the raw SEXP for a column by name.
416 #[inline]
417 pub fn column_raw(&self, name: &str) -> Option<SEXP> {
418 self.named_list().get_raw(name)
419 }
420
421 /// Number of rows.
422 #[inline]
423 pub fn nrow(&self) -> usize {
424 extract_nrow(self.sexp).unwrap_or(0)
425 }
426
427 /// Number of columns.
428 #[inline]
429 pub fn ncol(&self) -> usize {
430 self.sexp.len()
431 }
432
433 /// Collect column names in column order, each read with its own encoding
434 /// (a Latin-1 name is translated). An `NA` name reads as `""`, and a frame
435 /// without names gives an empty vector.
436 ///
437 /// # Errors
438 ///
439 /// A name marked as bytes, or one that is not valid UTF-8, is not text:
440 /// the error names every such column, 1-based (`marked as bytes, not text
441 /// (elements 2, 4)`). Refuse the frame with it rather than defaulting it
442 /// away: `unwrap_or_default()` would read a frame with one such name as a
443 /// frame with no names, and shift every other name off its column.
444 pub fn names(&self) -> Result<Vec<String>, SexpError> {
445 let names_sexp = self.sexp.get_names();
446 if names_sexp.is_nil() {
447 return Ok(Vec::new());
448 }
449 let names = <Vec<Option<String>> as TryFromSexp>::try_from_sexp(names_sexp)?;
450 Ok(names.into_iter().map(Option::unwrap_or_default).collect())
451 }
452
453 /// Check whether a column name exists.
454 #[inline]
455 pub fn contains_column(&self, name: &str) -> bool {
456 self.named_list().contains(name)
457 }
458
459 /// Validate the data frame's column types against a [`TypedListSpec`].
460 pub fn validate(&self, spec: &TypedListSpec) -> Result<TypedList, TypedListError> {
461 validate_list(unsafe { List::from_raw(self.sexp) }, spec)
462 }
463 // endregion
464
465 // region: Conversions
466
467 /// Get the underlying [`List`].
468 #[inline]
469 pub fn as_list(&self) -> List {
470 unsafe { List::from_raw(self.sexp) }
471 }
472
473 /// Get the underlying SEXP.
474 #[inline]
475 pub fn as_sexp(&self) -> SEXP {
476 self.sexp
477 }
478
479 /// Build the `NamedList` index for O(1) column-by-name access.
480 #[inline]
481 fn named_list(&self) -> NamedList {
482 NamedList::new(unsafe { List::from_raw(self.sexp) })
483 .expect("DataFrame always carries a names attribute")
484 }
485 // endregion
486
487 // region: Post-assembly editing (absorbed from the old serde columnar assembler)
488
489 /// Rename a column. No-op if `from` doesn't match any column name.
490 ///
491 /// In-place edit of the `names` attribute — returns the **same** frame (and
492 /// therefore inherits whatever root the input already had), unlike the
493 /// new-frame producers ([`drop`](Self::drop) and friends), which return a
494 /// rooted [`BuiltDataFrame`]. On a `BuiltDataFrame` receiver the inherent
495 /// forward ([`BuiltDataFrame::rename`]) keeps the handle instead.
496 ///
497 /// Other attributes are untouched, so renaming a grouping column of a
498 /// dplyr `grouped_df` leaves its `groups` naming the old column (#1702).
499 pub fn rename(self, from: &str, to: &str) -> Self {
500 unsafe {
501 // Root `self.sexp` so its `names` attribute survives the
502 // `SEXP::charsxp` (Rf_mkCharLenCE) allocation below, which can GC.
503 let _guard = crate::OwnedProtect::new(self.sexp);
504 let names_sexp = self.sexp.get_names();
505 if names_sexp == SEXP::nil() {
506 return self;
507 }
508 let ncol = names_sexp.xlength();
509 for i in 0..ncol {
510 if col_name(names_sexp, i) == Some(from) {
511 names_sexp.set_string_elt(i, SEXP::charsxp(to));
512 break;
513 }
514 }
515 }
516 self
517 }
518
519 /// Strip a prefix from all column names that start with it.
520 ///
521 /// In-place edit of the `names` attribute — returns the **same** frame; see
522 /// [`rename`](Self::rename)'s rooting note.
523 pub fn strip_prefix(self, prefix: &str) -> Self {
524 unsafe {
525 // Root `self.sexp` so its `names` attribute survives the
526 // `SEXP::charsxp` (Rf_mkCharLenCE) allocation below, which can GC.
527 let _guard = crate::OwnedProtect::new(self.sexp);
528 let names_sexp = self.sexp.get_names();
529 if names_sexp == SEXP::nil() {
530 return self;
531 }
532 let ncol = names_sexp.xlength();
533 for i in 0..ncol {
534 let stripped = col_name(names_sexp, i).and_then(|name| name.strip_prefix(prefix));
535 if let Some(stripped) = stripped {
536 names_sexp.set_string_elt(i, SEXP::charsxp(stripped));
537 }
538 }
539 }
540 self
541 }
542
543 /// Remove a column by name. No-op if the column doesn't exist.
544 ///
545 /// # Frame attributes
546 ///
547 /// The new frame keeps every attribute of the input except `names`: its
548 /// `class`, `row.names`, and anything else on the frame (a `units` map, a
549 /// package's metadata), as `dplyr::select()` and tibble's `[` do. This
550 /// holds for every column producer ([`select`](Self::select),
551 /// [`prepend_column`](Self::prepend_column),
552 /// [`with_column`](Self::with_column)).
553 ///
554 /// A dplyr `grouped_df` / `rowwise_df` keeps its grouping while every
555 /// grouping column is still there, unchanged. Removing or replacing one
556 /// returns the ungrouped frame instead (no `groups` attribute, no
557 /// `grouped_df` / `rowwise_df` class), where dplyr's `[` would regroup by
558 /// the grouping columns that remain.
559 ///
560 /// # Rooting
561 ///
562 /// Returns an owned, GC-rooted [`BuiltDataFrame`] (#1247): the result frame
563 /// is rooted before this method returns, so holding it across R allocations
564 /// is safe by construction. The no-op path re-roots the input frame (each
565 /// `BuiltDataFrame` releases exactly its own root — `R_PreserveObject`
566 /// entries stack, so re-rooting an already-rooted SEXP is sound).
567 ///
568 /// The input view must be reachable when calling (the usual [`DataFrame`]
569 /// view contract: an R `.Call` argument frame, a
570 /// [`ProtectScope`](crate::ProtectScope), or a live [`BuiltDataFrame`]).
571 #[must_use]
572 pub fn drop(self, col: &str) -> BuiltDataFrame {
573 unsafe {
574 let names_sexp = self.sexp.get_names();
575 if names_sexp == SEXP::nil() {
576 return BuiltDataFrame::adopt(self);
577 }
578 let ncol = names_sexp.xlength();
579 let drop_idx = (0..ncol).find(|&i| col_name(names_sexp, i) == Some(col));
580 let Some(drop_idx) = drop_idx else {
581 return BuiltDataFrame::adopt(self);
582 };
583
584 let new_ncol = ncol - 1;
585 let new_list = crate::OwnedProtect::new(SEXP::alloc_list(new_ncol));
586 let new_names = crate::OwnedProtect::new(SEXP::alloc_strsxp(new_ncol));
587
588 let mut j: isize = 0;
589 for i in 0..ncol {
590 if i == drop_idx {
591 continue;
592 }
593 new_list.set_vector_elt(j, self.sexp.vector_elt(i));
594 new_names.set_string_elt(j, names_sexp.string_elt(i));
595 j += 1;
596 }
597
598 new_list.set_names(*new_names);
599 copy_frame_attrs(self.sexp, *new_list, true);
600
601 // Root the new frame before the OwnedProtect guards drop:
602 // `adopt_sexp` preserves first (protecting `new_list` across its own
603 // cons-cell allocation), the guards UNPROTECT after — no gap.
604 BuiltDataFrame::adopt_sexp(*new_list)
605 }
606 }
607
608 /// Keep only the named columns, in the order given. Unknown names are skipped.
609 ///
610 /// Keeps the frame's attributes and, while every grouping column is
611 /// selected, its dplyr grouping; see [`drop`](Self::drop)'s frame-attribute
612 /// note.
613 ///
614 /// # Rooting
615 ///
616 /// Returns an owned, GC-rooted [`BuiltDataFrame`] — see
617 /// [`drop`](Self::drop)'s rooting note (#1247).
618 #[must_use]
619 pub fn select(self, cols: &[&str]) -> BuiltDataFrame {
620 unsafe {
621 let names_sexp = self.sexp.get_names();
622 if names_sexp == SEXP::nil() {
623 return BuiltDataFrame::adopt(self);
624 }
625 let ncol = names_sexp.xlength();
626
627 let indices: Vec<isize> = cols
628 .iter()
629 .filter_map(|&want| (0..ncol).find(|&i| col_name(names_sexp, i) == Some(want)))
630 .collect();
631
632 let new_ncol: isize = indices.len().try_into().expect("ncol overflow");
633 let new_list = crate::OwnedProtect::new(SEXP::alloc_list(new_ncol));
634 let new_names = crate::OwnedProtect::new(SEXP::alloc_strsxp(new_ncol));
635
636 for (j, &src_idx) in indices.iter().enumerate() {
637 let j_r: isize = j.try_into().expect("index overflow");
638 new_list.set_vector_elt(j_r, self.sexp.vector_elt(src_idx));
639 new_names.set_string_elt(j_r, names_sexp.string_elt(src_idx));
640 }
641
642 new_list.set_names(*new_names);
643 copy_frame_attrs(self.sexp, *new_list, true);
644
645 // Root before the guards drop (see `drop` for the ordering argument).
646 BuiltDataFrame::adopt_sexp(*new_list)
647 }
648 }
649
650 /// Keep only the rows at the given 0-based indices, in order.
651 ///
652 /// Subsets every column to the specified rows and rebuilds compact integer
653 /// `row.names`. Used by the enum reader to densify a flattened sub-frame
654 /// before recursing into the inner type's reader, and by group iteration.
655 ///
656 /// A row is a row of every column, as in `df[idx, , drop = FALSE]`:
657 ///
658 /// - A vector or list column is gathered by element, and its element
659 /// `names`, if any, are subset with the values.
660 /// - A column with a `dim` (an `I(matrix)` column, or an array) is gathered
661 /// along its first dimension: `dim` becomes `c(length(idx), dim[-1])` and
662 /// the first `dimnames` component (the row names) is subset, the rest kept.
663 /// Arrays of three or more dimensions follow `vctrs::vec_slice()` here;
664 /// base `[.data.frame` subsets those by element.
665 /// - A data.frame column (a packed column) is subset the same way,
666 /// recursively.
667 ///
668 /// Each column keeps all of its other attributes ([`SexpExt::copy_most_attrib`], the
669 /// `vctrs::vec_slice()` rule), so a `POSIXct` column keeps its `tzone`, a
670 /// `difftime` its `units` and an `I()` column its `AsIs` class.
671 ///
672 /// # Frame attributes
673 ///
674 /// The new frame keeps every attribute of the input frame except `names`
675 /// (the columns' names, as before) and `row.names` (fresh, `1:length(idx)`):
676 /// its `class`, and anything else on the frame, such as a `units` map
677 /// describing some columns or a package's metadata. This is what
678 /// `dplyr::slice()` (`dplyr_row_slice()` / `dplyr_reconstruct()`),
679 /// `vctrs::vec_slice()`, tibble's `[` and base `[.data.frame` keep on a row
680 /// subset. A packed data.frame column keeps its own the same way.
681 ///
682 /// dplyr's grouping does not survive. A `grouped_df` or `rowwise_df` caches
683 /// each group's row indices in its `groups` attribute, which no longer
684 /// matches the selected rows, so the result has no `groups` attribute and
685 /// no `grouped_df` / `rowwise_df` class: it is the ungrouped frame (a
686 /// tibble, for a dplyr input). `dplyr::slice()` recomputes the groups
687 /// instead. To keep the grouping, read it from the input with
688 /// [`group_declaration`](Self::group_declaration) and regroup the result,
689 /// in Rust with [`group_by_multi`](Self::group_by_multi) over its
690 /// [`vars`](crate::dataframe::GroupDeclaration::vars), or in R with
691 /// `dplyr::grouped_df(out, dplyr::group_vars(df))`.
692 ///
693 /// Any other attribute indexed by row is copied as it is. A package that
694 /// keeps one must rebuild it after a row subset, as dplyr's extension guide
695 /// (`?dplyr_row_slice`) asks of `dplyr_row_slice()` methods.
696 ///
697 /// # PROTECT discipline
698 ///
699 /// Allocates new column vectors (and `dim` / `dimnames` for matrix columns)
700 /// while the output list is `OwnedProtect`ed, rooting each new column in it
701 /// before the next allocation.
702 ///
703 /// # Rooting
704 ///
705 /// Returns an owned, GC-rooted [`BuiltDataFrame`] — see
706 /// [`drop`](Self::drop)'s rooting note (#1247).
707 #[must_use]
708 pub fn select_rows(&self, idx: &[usize]) -> BuiltDataFrame {
709 unsafe {
710 let out = select_frame_rows(self.sexp, idx);
711 // Root before the guard drops (see `drop` for the ordering argument).
712 BuiltDataFrame::adopt_sexp(*out)
713 }
714 }
715
716 /// Insert a column at index 0 (leftmost), removing any same-named column first.
717 ///
718 /// Keeps the frame's attributes and its dplyr grouping, unless `name`
719 /// replaces a grouping column; see [`drop`](Self::drop)'s frame-attribute
720 /// note.
721 ///
722 /// # Rooting
723 ///
724 /// Returns an owned, GC-rooted [`BuiltDataFrame`] — see
725 /// [`drop`](Self::drop)'s rooting note (#1247). `column` must be kept
726 /// reachable by the caller (e.g. under an
727 /// [`OwnedProtect`](crate::OwnedProtect)) across this call — the new frame
728 /// is allocated before `column` is stored into it.
729 #[must_use]
730 pub fn prepend_column(self, name: &str, column: SEXP) -> BuiltDataFrame {
731 // `drop` returns a rooted handle, so the intermediate frame survives the
732 // allocations below (pre-#1247 this was an unrooted view — a latent UAF
733 // window inside this very method).
734 let cleaned = self.drop(name);
735 unsafe {
736 let names_sexp = cleaned.as_sexp().get_names();
737 let ncol = if names_sexp == SEXP::nil() {
738 0
739 } else {
740 names_sexp.xlength()
741 };
742
743 let new_ncol = ncol + 1;
744 let new_list = crate::OwnedProtect::new(SEXP::alloc_list(new_ncol));
745 let new_names = crate::OwnedProtect::new(SEXP::alloc_strsxp(new_ncol));
746
747 new_list.set_vector_elt(0, column);
748 new_names.set_string_elt(0, SEXP::charsxp(name));
749
750 for i in 0..ncol {
751 new_list.set_vector_elt(i + 1, cleaned.as_sexp().vector_elt(i));
752 new_names.set_string_elt(i + 1, names_sexp.string_elt(i));
753 }
754
755 new_list.set_names(*new_names);
756 copy_frame_attrs(cleaned.as_sexp(), *new_list, true);
757
758 // Root before the guards (and `cleaned`) drop — see `drop` for the
759 // ordering argument.
760 BuiltDataFrame::adopt_sexp(*new_list)
761 }
762 }
763
764 /// Upsert a column: replace the column named `name` if it exists, else append.
765 ///
766 /// The append path builds a new frame that keeps the input's attributes
767 /// and dplyr grouping (see [`drop`](Self::drop)'s frame-attribute note).
768 /// The replace path stores `column` into the input frame itself and
769 /// returns that frame, attributes untouched, so replacing a grouping
770 /// column leaves dplyr's `groups` stale (#1702).
771 ///
772 /// # Rooting
773 ///
774 /// Both paths return an owned, GC-rooted [`BuiltDataFrame`] (#1247) — the
775 /// in-place replace path re-roots the same frame it received (sound:
776 /// `R_PreserveObject` entries stack; this handle releases exactly one).
777 /// `column` must be kept reachable by the caller across this call — the
778 /// append path allocates the new frame before `column` is stored into it.
779 #[must_use]
780 pub fn with_column(self, name: &str, column: SEXP) -> BuiltDataFrame {
781 unsafe {
782 let names_sexp = self.sexp.get_names();
783 if names_sexp == SEXP::nil() {
784 return BuiltDataFrame::adopt(self);
785 }
786 let ncol = names_sexp.xlength();
787 for i in 0..ncol {
788 if col_name(names_sexp, i) == Some(name) {
789 // set_vector_elt does not allocate; `column` is reachable
790 // from the (caller-rooted) frame before `adopt` allocates
791 // its cons cell.
792 self.sexp.set_vector_elt(i, column);
793 return BuiltDataFrame::adopt(self);
794 }
795 }
796
797 let new_ncol = ncol + 1;
798 let new_list = crate::OwnedProtect::new(SEXP::alloc_list(new_ncol));
799 let new_names = crate::OwnedProtect::new(SEXP::alloc_strsxp(new_ncol));
800
801 for i in 0..ncol {
802 new_list.set_vector_elt(i, self.sexp.vector_elt(i));
803 new_names.set_string_elt(i, names_sexp.string_elt(i));
804 }
805 new_list.set_vector_elt(ncol, column);
806 new_names.set_string_elt(ncol, SEXP::charsxp(name));
807
808 new_list.set_names(*new_names);
809 copy_frame_attrs(self.sexp, *new_list, true);
810
811 // Root before the guards drop (see `drop` for the ordering argument).
812 BuiltDataFrame::adopt_sexp(*new_list)
813 }
814 }
815 // endregion
816
817 // region: builder (ex-RDataFrameBuilder, #768)
818
819 /// Start a closure-per-column builder yielding a rooted [`BuiltDataFrame`].
820 ///
821 /// The heterogeneous-column analogue of `with_r_matrix`: each column buffer is R memory
822 /// filled by a per-column closure. Available regardless of the `rayon` feature (#1055);
823 /// the columns are filled **in parallel** when `rayon` is enabled and **serially**
824 /// otherwise — the resulting `data.frame` is identical either way.
825 ///
826 /// ```ignore
827 /// let df = DataFrame::builder(1000)
828 /// .column::<f64>("x", |chunk, off| for (i, v) in chunk.iter_mut().enumerate() { *v = (off + i) as f64 })
829 /// .column_str("label", |i| Some(format!("row{i}")))
830 /// .build();
831 /// ```
832 #[inline]
833 pub fn builder(nrow: usize) -> crate::dataframe_builder::RDataFrameBuilder {
834 crate::dataframe_builder::RDataFrameBuilder::new(nrow)
835 }
836 // endregion
837}
838// endregion
839
840// region: column-name helper + frame-attribute copy
841
842/// Read the i-th column name from a STRSXP names vector, as a name lookup
843/// reads it ([`crate::list::text_name`]): a Latin-1 name is translated, and
844/// `NA` or a name that is not text (marked as bytes) is `None`, which no
845/// lookup matches.
846///
847/// # Safety
848/// `names_sexp` must be a valid STRSXP with at least `i + 1` elements.
849unsafe fn col_name(names_sexp: SEXP, i: isize) -> Option<&'static str> {
850 crate::list::text_name(names_sexp.string_elt(i))
851}
852
853/// The body of [`DataFrame::select_rows`]: row-subset the data.frame VECSXP
854/// `frame` at the 0-based rows `idx`. Shared with packed data.frame columns.
855///
856/// Returns the new frame still protected; the caller roots it before the guard
857/// drops.
858///
859/// # Safety
860///
861/// R main thread; `frame` is a data.frame list whose columns all have at least
862/// `max(idx) + 1` rows.
863unsafe fn select_frame_rows(frame: SEXP, idx: &[usize]) -> crate::OwnedProtect {
864 use crate::SexpExt as _;
865
866 unsafe {
867 let names_sexp = frame.get_names();
868 let ncol = frame.xlength();
869 let new_nrow = i32::try_from(idx.len()).expect("row count exceeds i32::MAX");
870
871 let new_list = crate::OwnedProtect::new(SEXP::alloc_list(ncol));
872 {
873 let new_names = crate::OwnedProtect::new(SEXP::alloc_strsxp(ncol));
874
875 for col_j in 0..ncol {
876 let src_col = frame.vector_elt(col_j);
877 // Protected on return; rooted in the protected `new_list` before
878 // its guard (the top of the protect stack) drops.
879 let new_col = select_column_rows(src_col, idx);
880 new_list.set_vector_elt(col_j, *new_col);
881 drop(new_col);
882 if names_sexp != SEXP::nil() {
883 new_names.set_string_elt(col_j, names_sexp.string_elt(col_j));
884 }
885 }
886
887 if names_sexp != SEXP::nil() {
888 new_list.set_names(*new_names);
889 }
890 }
891
892 // Every frame attribute of the source (`class` included), with dplyr's
893 // row-indexed `groups` removed. This copies the source's `row.names`
894 // too, so it runs before the fresh ones are set below.
895 copy_frame_attrs(frame, *new_list, false);
896
897 // Set compact integer row.names (c(NA_integer_, -new_nrow)).
898 let (row_names, rn) = crate::into_r::alloc_r_vector::<i32>(2);
899 {
900 let _rn_guard = crate::OwnedProtect::new(row_names);
901 rn[0] = i32::MIN;
902 rn[1] = -new_nrow;
903 new_list.set_row_names(row_names);
904 }
905
906 new_list
907 }
908}
909
910/// Row-subset one data.frame column at the 0-based rows `idx` (see
911/// [`DataFrame::select_rows`] for the per-kind rules). Returns it protected.
912///
913/// # Safety
914///
915/// R main thread; `col` is a valid column with at least `max(idx) + 1` rows.
916unsafe fn select_column_rows(col: SEXP, idx: &[usize]) -> crate::OwnedProtect {
917 use crate::SexpExt as _;
918
919 unsafe {
920 if col.type_of() == SEXPTYPE::VECSXP && col.is_data_frame() {
921 return select_frame_rows(col, idx);
922 }
923
924 let dim = col.get_dim();
925 if dim.type_of() != SEXPTYPE::INTSXP || dim.xlength() == 0 {
926 // A plain vector or list column: a row is an element.
927 let out = crate::OwnedProtect::new(crate::convert::gather_column(col, idx));
928 // Every attribute except names/dim/dimnames, as `vctrs::vec_slice()`
929 // does: `class` and `levels` (factor, Date), `tzone` (POSIXct), `units`
930 // (difftime), labels, and anything else a package keeps on a column.
931 // Base `[` would drop the last kind on an unclassed column; a row
932 // subset should not change a column's meaning.
933 out.copy_most_attrib(col);
934 // Element names are per row, so they are subset with the values.
935 let col_names = col.get_names();
936 if col_names != SEXP::nil() {
937 let new_names =
938 crate::OwnedProtect::new(crate::convert::gather_column(col_names, idx));
939 out.set_names(*new_names);
940 }
941 return out;
942 }
943
944 // A matrix or array column: a row is one index of the first dimension,
945 // taken at every position of the trailing dimensions (column-major).
946 let dims: Vec<usize> = dim
947 .as_slice::<i32>()
948 .iter()
949 .map(|&d| usize::try_from(d).expect("dim entries are non-negative"))
950 .collect();
951 let nrow = dims[0];
952 let trailing: usize = dims[1..].iter().product();
953 let flat: Vec<usize> = (0..trailing)
954 .flat_map(|k| idx.iter().map(move |&row| row + k * nrow))
955 .collect();
956
957 let out = crate::OwnedProtect::new(crate::convert::gather_column(col, &flat));
958 out.copy_most_attrib(col);
959
960 {
961 let (new_dim, dim_vals) = crate::into_r::alloc_r_vector::<i32>(dims.len());
962 let _dim_guard = crate::OwnedProtect::new(new_dim);
963 dim_vals[0] = i32::try_from(idx.len()).expect("row count exceeds i32::MAX");
964 dim_vals[1..].copy_from_slice(&dim.as_slice::<i32>()[1..]);
965 out.set_dim(new_dim);
966 }
967
968 let dimnames = col.get_dimnames();
969 if dimnames != SEXP::nil() {
970 let n = dimnames.xlength();
971 let new_dimnames = crate::OwnedProtect::new(SEXP::alloc_list(n));
972 let row_names = dimnames.vector_elt(0);
973 if row_names != SEXP::nil() {
974 // Unprotected until the `set_vector_elt` right after, which does
975 // not allocate.
976 new_dimnames.set_vector_elt(0, crate::convert::gather_column(row_names, idx));
977 }
978 for i in 1..n {
979 new_dimnames.set_vector_elt(i, dimnames.vector_elt(i));
980 }
981 let dimnames_names = dimnames.get_names();
982 if dimnames_names != SEXP::nil() {
983 new_dimnames.set_names(dimnames_names);
984 }
985 out.set_dimnames(*new_dimnames);
986 }
987
988 out
989 }
990}
991
992/// Copy the frame attributes of `from` onto the new frame `to`.
993///
994/// Every attribute except `names` is copied ([`SexpExt::copy_most_attrib`]), the rule
995/// `vctrs::vec_slice()`, tibble's `[` and `dplyr_reconstruct()` follow:
996/// `class`, `row.names` (verbatim; a producer that changes the rows sets its
997/// own afterwards) and anything else a package keeps on the frame, such as a
998/// `units` map or its metadata.
999///
1000/// dplyr's grouping is the exception. A `grouped_df` / `rowwise_df` caches
1001/// its groups in a `groups` attribute that names the key columns and holds
1002/// each group's row indices, so it is copied only while it still describes
1003/// `to`: `same_rows`, and every grouping variable is the very column it was
1004/// in `from` (moved, not rebuilt or replaced). Otherwise `to` loses `groups`
1005/// and the `grouped_df` / `rowwise_df` class and is the ungrouped frame (a
1006/// tibble, for a dplyr input), never a grouped frame whose groups are stale.
1007///
1008/// # Safety
1009///
1010/// R main thread; `from` is a data.frame list and `to` a list whose `names`
1011/// are set, protected by the caller.
1012unsafe fn copy_frame_attrs(from: SEXP, to: SEXP, same_rows: bool) {
1013 unsafe {
1014 to.copy_most_attrib(from);
1015 let grouped = from.inherits_class(c"grouped_df") || from.inherits_class(c"rowwise_df");
1016 if grouped && !(same_rows && grouping_columns_kept(from, to)) {
1017 ungroup_frame(to);
1018 }
1019 }
1020}
1021
1022/// Whether every grouping variable of the grouped frame `from` (the columns
1023/// its `groups` attribute names, `.rows` aside) is a column of `to` that is
1024/// the same SEXP as in `from`. `false` when `groups` is not a data frame.
1025///
1026/// # Safety
1027///
1028/// R main thread; `from` and `to` are data.frame lists.
1029unsafe fn grouping_columns_kept(from: SEXP, to: SEXP) -> bool {
1030 unsafe {
1031 let groups = from.get_attr(crate::sys::Rf_install(c"groups".as_ptr()));
1032 if groups.type_of() != SEXPTYPE::VECSXP || !groups.is_data_frame() {
1033 return false;
1034 }
1035 let vars = groups.get_names();
1036 if vars == SEXP::nil() {
1037 return false;
1038 }
1039 (0..vars.xlength())
1040 .map(|i| col_name(vars, i))
1041 .filter(|&var| var != Some(".rows"))
1042 .all(|var| {
1043 let Some(var) = var else { return false };
1044 match (column_named(from, var), column_named(to, var)) {
1045 (Some(before), Some(after)) => before == after,
1046 _ => false,
1047 }
1048 })
1049 }
1050}
1051
1052/// The first column of the data.frame list `frame` named `name`.
1053///
1054/// # Safety
1055///
1056/// R main thread; `frame` is a list.
1057unsafe fn column_named(frame: SEXP, name: &str) -> Option<SEXP> {
1058 unsafe {
1059 let names = frame.get_names();
1060 if names == SEXP::nil() {
1061 return None;
1062 }
1063 (0..names.xlength())
1064 .find(|&i| col_name(names, i) == Some(name))
1065 .map(|i| frame.vector_elt(i))
1066 }
1067}
1068
1069/// Remove dplyr's grouping from the frame `to`: its `groups` attribute and
1070/// the `grouped_df` / `rowwise_df` entries of its class.
1071///
1072/// # Safety
1073///
1074/// R main thread; `to` is a data.frame list protected by the caller.
1075unsafe fn ungroup_frame(to: SEXP) {
1076 unsafe {
1077 to.set_attr(crate::sys::Rf_install(c"groups".as_ptr()), SEXP::nil());
1078 // Still attached to (and so rooted by) `to` until `set_class` below.
1079 let class = to.get_class();
1080 let kept: Vec<isize> = (0..class.xlength())
1081 .filter(|&i| !matches!(col_name(class, i), Some("grouped_df" | "rowwise_df")))
1082 .collect();
1083 let new_class = crate::OwnedProtect::new(SEXP::alloc_strsxp(
1084 isize::try_from(kept.len()).expect("class length fits isize"),
1085 ));
1086 for (j, &i) in kept.iter().enumerate() {
1087 new_class.set_string_elt(
1088 isize::try_from(j).expect("class length fits isize"),
1089 class.string_elt(i),
1090 );
1091 }
1092 to.set_class(*new_class);
1093 }
1094}
1095// endregion
1096
1097// region: IntoR / TryFromSexp for DataFrame
1098
1099impl TryFromSexp for DataFrame {
1100 type Error = SexpError;
1101
1102 // As an `Either` arm, a data frame refuses nothing under `no_na`: its
1103 // cells may be missing, and reading them is the function's own business.
1104 // (A `DataFrame` parameter keeps the R guard, which refuses any NA cell.)
1105 #[inline]
1106 fn __mx_input_has_na(&self, _input: SEXP) -> bool {
1107 false
1108 }
1109
1110 fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1111 // Not a data frame at all (a non-list, or a list without the class) is
1112 // a class error, worded `got integer` / `got list` by the argument
1113 // error; a data frame that fails later keeps its own message.
1114 let not_a_data_frame = |actual| {
1115 SexpClassError {
1116 expected: "a data frame",
1117 actual,
1118 }
1119 .into()
1120 };
1121 DataFrame::from_sexp(sexp).map_err(|e| match e {
1122 DataFrameError::NotList(actual) => not_a_data_frame(actual),
1123 DataFrameError::NotDataFrame => not_a_data_frame(SEXPTYPE::VECSXP),
1124 other => SexpError::InvalidValue(other.to_string()),
1125 })
1126 }
1127}
1128
1129/// `NULL` → `None`; any other value converts as a [`DataFrame`] (same view,
1130/// attributes and `NA` cells, same error) and becomes `Some`.
1131///
1132/// Concrete rather than left to the newtype blanket `Option<T>` impl
1133/// (`newtype.rs`), which `DataFrame` does not match: without this impl,
1134/// `Option<DataFrame>: TryFromSexp` fails with E0275 (overflow) instead of
1135/// converting.
1136impl TryFromSexp for Option<DataFrame> {
1137 type Error = <DataFrame as TryFromSexp>::Error;
1138 const NATIVE_BORROW: Option<crate::from_r::NativeBorrow> =
1139 <DataFrame as TryFromSexp>::NATIVE_BORROW;
1140 const CHARACTER_ONLY: bool = <DataFrame as TryFromSexp>::CHARACTER_ONLY;
1141 // `__MX_EXPECTATION` keeps its `None`: the inner text without `NULL or`
1142 // would be wrong, and `#[miniextendr]` words an `Option<_>` parameter or
1143 // arm itself (`NULL or <T>`).
1144
1145 // `NULL` (`None`) is "not given" and passes `no_na`.
1146 #[inline]
1147 fn __mx_has_na(&self) -> bool {
1148 self.as_ref()
1149 .is_some_and(<DataFrame as TryFromSexp>::__mx_has_na)
1150 }
1151
1152 // As an `Either` arm, a given frame is read by `DataFrame` (it keeps its
1153 // `NA` cells); `NULL` holds no `NA`.
1154 #[inline]
1155 fn __mx_input_has_na(&self, input: SEXP) -> bool {
1156 match self {
1157 Some(df) => <DataFrame as TryFromSexp>::__mx_input_has_na(df, input),
1158 None => false,
1159 }
1160 }
1161
1162 #[inline]
1163 fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
1164 if sexp.type_of() == SEXPTYPE::NILSXP {
1165 Ok(None)
1166 } else {
1167 <DataFrame as TryFromSexp>::try_from_sexp(sexp).map(Some)
1168 }
1169 }
1170
1171 #[inline]
1172 unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
1173 if sexp.type_of() == SEXPTYPE::NILSXP {
1174 Ok(None)
1175 } else {
1176 unsafe { <DataFrame as TryFromSexp>::try_from_sexp_unchecked(sexp) }.map(Some)
1177 }
1178 }
1179}
1180
1181impl IntoR for DataFrame {
1182 type Error = std::convert::Infallible;
1183 fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1184 Ok(self.sexp)
1185 }
1186 unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1187 Ok(self.sexp)
1188 }
1189 #[inline]
1190 fn into_sexp(self) -> SEXP {
1191 self.sexp
1192 }
1193}
1194// endregion
1195
1196// region: BuiltDataFrame — owned, GC-rooted, Rust-constructed data.frame
1197
1198/// An owned, GC-rooted `data.frame` **built on the Rust side**.
1199///
1200/// [`DataFrame`] is a cheap `Copy` *view* over a bare SEXP with no root of its
1201/// own — sound only while something else keeps the SEXP reachable (an R `.Call`
1202/// argument frame roots R-supplied frames; a surrounding
1203/// [`ProtectScope`](crate::ProtectScope) roots transients). A frame that Rust
1204/// *constructs* has no such external root, so holding the bare view across any R
1205/// allocation is a latent use-after-free (issue #1128): the GC reclaims the
1206/// frame, and a freed-but-intact read passes tests silently until the slot is
1207/// reused.
1208///
1209/// `BuiltDataFrame` is the return type of every Rust-side constructor
1210/// ([`IntoDataFrame::into_dataframe`], `SerdeRowBuilder::finish`,
1211/// [`DataFrame::builder`]`().build()`, the serde `*_to_dataframe` verbs,
1212/// [`NamedList::as_data_frame`]), and the partition type inside the split verbs'
1213/// [`DataFrameShape`] ([`IntoDataFrameSplit::into_dataframe_split`], #1750; the
1214/// serde `vec_to_dataframe_split` / `result_to_dataframe`, #1265). It roots the
1215/// frame with a [`Preserved`](crate::Preserved) handle (`R_PreserveObject` on
1216/// construction, `R_ReleaseObject` on drop), so holding it across allocations
1217/// is safe by construction. It [`Deref`](std::ops::Deref)s to
1218/// [`DataFrame`], so every read/edit method keeps working unchanged; hand the
1219/// frame back to R with [`IntoR::into_sexp`] — or just return it from a
1220/// `#[miniextendr]` fn, which converts it through [`IntoR`] transparently.
1221///
1222/// Not `Copy`/`Clone` (each root is released exactly once) and not `Send`
1223/// (R's precious list is R-main-thread state).
1224///
1225/// # Editing (chains stay rooted, #1247)
1226///
1227/// The new-frame editing methods ([`DataFrame::drop`], [`DataFrame::select`],
1228/// [`DataFrame::select_rows`], [`DataFrame::prepend_column`],
1229/// [`DataFrame::with_column`]) also return `BuiltDataFrame`, and this type
1230/// carries inherent forwards for the whole editing set, so
1231/// `rows.into_dataframe()?.drop("x").select(&["y"])` is rooted at every link.
1232///
1233/// # Residual
1234///
1235/// The cheap view can still be *smuggled* across allocations by hand:
1236/// dereferencing (`*built`) copies out an unrooted `DataFrame` view that
1237/// dangles once the handle drops. That is an opt-in footgun, not the
1238/// constructor/editing path this type makes safe.
1239pub struct BuiltDataFrame {
1240 view: DataFrame,
1241 /// Roots `view`'s frame for as long as the handle lives.
1242 root: crate::Preserved,
1243}
1244
1245impl BuiltDataFrame {
1246 /// Root an already-built `data.frame` SEXP and take ownership of the root.
1247 ///
1248 /// # Safety
1249 ///
1250 /// Must run on the R main thread. `sexp` must be a well-formed `data.frame`
1251 /// VECSXP. Rooting is immediate (see [`Preserved::new`](crate::Preserved::new)),
1252 /// so a freshly-assembled unprotected SEXP is safe to pass directly.
1253 #[inline]
1254 pub unsafe fn adopt_sexp(sexp: SEXP) -> Self {
1255 // SAFETY: as documented on this fn.
1256 unsafe { Self::from_root(crate::Preserved::new(sexp)) }
1257 }
1258
1259 /// Root a [`DataFrame`] view, taking ownership of a fresh root.
1260 ///
1261 /// Rooting an already-rooted frame is sound: `R_PreserveObject` entries
1262 /// stack (the precious list is a cons list, duplicates allowed), and each
1263 /// `BuiltDataFrame` releases exactly the one entry it added.
1264 ///
1265 /// # Safety
1266 ///
1267 /// Must run on the R main thread. `df` must wrap a well-formed, still-live
1268 /// `data.frame` VECSXP (reachable at the moment of the call).
1269 #[inline]
1270 pub unsafe fn adopt(df: DataFrame) -> Self {
1271 // SAFETY: as documented on this fn.
1272 unsafe { Self::adopt_sexp(df.as_sexp()) }
1273 }
1274
1275 /// Take over an existing root of a frame.
1276 ///
1277 /// # Safety
1278 ///
1279 /// `root` holds a well-formed `data.frame` VECSXP.
1280 #[inline]
1281 pub(crate) unsafe fn from_root(root: crate::Preserved) -> Self {
1282 Self {
1283 // SAFETY: caller guarantees `root` holds a well-formed data.frame VECSXP.
1284 view: unsafe { DataFrame::from_built_sexp(root.as_sexp()) },
1285 root,
1286 }
1287 }
1288
1289 // region: editing forwards (#1247) — keep chains rooted at every link
1290 //
1291 // These consume the handle (`self` stays alive until the tail expression
1292 // has produced — and rooted — the result, so the input frame is reachable
1293 // throughout the edit; its root is then released with no allocation in
1294 // between). Plain `Deref` would instead copy out the view and return the
1295 // view method's result, rooted or not.
1296
1297 /// Remove a column by name — see [`DataFrame::drop`].
1298 ///
1299 /// Inherent forward: consumes this handle and returns the rooted result.
1300 #[must_use]
1301 pub fn drop(self, col: &str) -> BuiltDataFrame {
1302 (*self).drop(col)
1303 }
1304
1305 /// Keep only the named columns — see [`DataFrame::select`].
1306 #[must_use]
1307 pub fn select(self, cols: &[&str]) -> BuiltDataFrame {
1308 (*self).select(cols)
1309 }
1310
1311 /// Keep only the given rows — see [`DataFrame::select_rows`].
1312 #[must_use]
1313 pub fn select_rows(&self, idx: &[usize]) -> BuiltDataFrame {
1314 (**self).select_rows(idx)
1315 }
1316
1317 /// Insert a column at index 0 — see [`DataFrame::prepend_column`].
1318 ///
1319 /// `column` must be kept reachable by the caller across this call.
1320 #[must_use]
1321 pub fn prepend_column(self, name: &str, column: SEXP) -> BuiltDataFrame {
1322 (*self).prepend_column(name, column)
1323 }
1324
1325 /// Upsert a column — see [`DataFrame::with_column`].
1326 ///
1327 /// `column` must be kept reachable by the caller across this call.
1328 #[must_use]
1329 pub fn with_column(self, name: &str, column: SEXP) -> BuiltDataFrame {
1330 (*self).with_column(name, column)
1331 }
1332
1333 /// Rename a column — see [`DataFrame::rename`].
1334 ///
1335 /// In-place edit of the same frame: this handle (and its root) carries
1336 /// straight through.
1337 #[must_use]
1338 pub fn rename(self, from: &str, to: &str) -> BuiltDataFrame {
1339 let _ = (*self).rename(from, to);
1340 self
1341 }
1342
1343 /// Strip a prefix from column names — see [`DataFrame::strip_prefix`].
1344 ///
1345 /// In-place edit of the same frame: this handle (and its root) carries
1346 /// straight through.
1347 #[must_use]
1348 pub fn strip_prefix(self, prefix: &str) -> BuiltDataFrame {
1349 let _ = (*self).strip_prefix(prefix);
1350 self
1351 }
1352 // endregion
1353}
1354
1355impl std::ops::Deref for BuiltDataFrame {
1356 type Target = DataFrame;
1357 #[inline]
1358 fn deref(&self) -> &DataFrame {
1359 &self.view
1360 }
1361}
1362
1363/// Releases the root and hands the frame over, unprotected, as
1364/// [`DataFrame::as_sexp`] / [`IntoR::into_sexp`] do: the caller (typically the
1365/// `.Call` return path) takes over protection. `R_ReleaseObject` does not
1366/// allocate, so no GC can run between the release and the return.
1367impl IntoR for BuiltDataFrame {
1368 type Error = std::convert::Infallible;
1369 fn try_into_sexp(self) -> Result<SEXP, Self::Error> {
1370 Ok(self.root.into_sexp())
1371 }
1372 unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error> {
1373 Ok(self.root.into_sexp())
1374 }
1375 #[inline]
1376 fn into_sexp(self) -> SEXP {
1377 self.root.into_sexp()
1378 }
1379}
1380
1381impl std::fmt::Debug for BuiltDataFrame {
1382 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1383 f.debug_struct("BuiltDataFrame")
1384 .field("nrow", &self.nrow())
1385 .field("ncol", &self.ncol())
1386 .finish()
1387 }
1388}
1389// endregion
1390
1391// region: The conversion trait family (mirrors IntoR / TryFromSexp)
1392
1393/// Rust data → R `data.frame`. The data-frame analogue of [`IntoR`].
1394///
1395/// Implemented for `Vec<Row>` when `Row` derives `DataFrameRow` (struct or enum), and by the
1396/// serde column path. Call it on your data: `rows.into_dataframe()?`.
1397///
1398/// Borrowed rows convert too: `rows.as_slice().into_dataframe()?` or
1399/// `(&rows).into_dataframe()?` (`&[Row]` / `&Vec<Row>`) build the same frame without
1400/// consuming the rows, which is what a `&self` method holding a `Vec<Row>` needs.
1401/// `String` and `Option<String>` columns are then written from `&str`, and every other
1402/// field value is cloned once into its column, so those field types need `Clone`.
1403///
1404/// # Parallel fast path
1405///
1406/// `into_dataframe_par` (present only with
1407/// `feature = "rayon"`) produces the **same** [`BuiltDataFrame`] as
1408/// [`into_dataframe`](IntoDataFrame::into_dataframe). It defaults to the sequential path, so
1409/// every implementor gets a correct `_par` for free; `#[derive(DataFrameRow)]` row types
1410/// override it with a genuinely parallel column fill (the #777 flattened `(column,row-range)`
1411/// work-list). The verb is stable across feature sets — dropping `_par` degrades cleanly to
1412/// the sequential call.
1413pub trait IntoDataFrame: Sized {
1414 /// Convert this value into an owned, GC-rooted [`BuiltDataFrame`].
1415 fn into_dataframe(self) -> Result<BuiltDataFrame, DataFrameError>;
1416
1417 /// Parallel column fill (`feature = "rayon"`). Same result as `into_dataframe()`.
1418 ///
1419 /// Defaults to the sequential path; overridden by the derive for a real parallel fill.
1420 #[cfg(feature = "rayon")]
1421 fn into_dataframe_par(self) -> Result<BuiltDataFrame, DataFrameError> {
1422 self.into_dataframe()
1423 }
1424}
1425
1426/// R `data.frame` → Rust data. The data-frame analogue of
1427/// [`TryFromSexp`].
1428///
1429/// Implemented by `#[derive(DataFrameRow)]` for `Vec<Row>` and by the serde row path.
1430///
1431/// # Parallel fast path
1432///
1433/// `from_dataframe_par` (`feature = "rayon"`) reads the
1434/// same rows as [`from_dataframe`](FromDataFrame::from_dataframe), defaulting to the
1435/// sequential reader; the derive overrides it with the #765 off-main-thread row assembly.
1436pub trait FromDataFrame: Sized {
1437 /// Read rows back out of a [`DataFrame`].
1438 fn from_dataframe(df: &DataFrame) -> Result<Self, DataFrameError>;
1439
1440 /// Parallel row read (`feature = "rayon"`). Same result as `from_dataframe()`.
1441 #[cfg(feature = "rayon")]
1442 fn from_dataframe_par(df: &DataFrame) -> Result<Self, DataFrameError> {
1443 Self::from_dataframe(df)
1444 }
1445}
1446
1447/// Enum rows → variant-partitioned R `data.frame`s. The split-representation
1448/// sibling of [`IntoDataFrame`].
1449///
1450/// Where [`IntoDataFrame`] produces one **aligned** `data.frame` (field-name
1451/// union, `NA` fill for columns a variant doesn't carry), this verb partitions
1452/// the rows by variant: each partition is a `data.frame` with only that
1453/// variant's own columns (non-optional types — no `NA` fill from sibling
1454/// variants), keyed by the snake_case variant name.
1455///
1456/// Implemented by `#[derive(DataFrameRow)]` on an **enum** row type (for
1457/// `Vec<Row>`, via the hidden [`DataFrameRowSplit`] bridge below). Struct rows
1458/// have no variants to partition, so the struct derive does not provide it.
1459/// Call it on your data: `rows.into_dataframe_split()`.
1460///
1461/// # Return shape
1462///
1463/// The returned [`DataFrameShape`] says which R value the split produced:
1464///
1465/// - [`DataFrameShape::Bare`] — a single-variant enum: one `data.frame`.
1466/// - [`DataFrameShape::PerVariantList`] — a multi-variant enum: one
1467/// `(snake_case_name, data.frame)` entry per declared variant, in
1468/// declaration order, which converts to a named R list of `data.frame`s.
1469///
1470/// The derive never produces [`DataFrameShape::Split`] (that variant belongs to
1471/// the serde `result_to_dataframe` helper). Variants absent from the input
1472/// still appear as 0-row `data.frame`s with that variant's column shape; unit
1473/// variants produce a 0-column `data.frame` with the correct row count.
1474/// `DataFrameShape` is [`IntoR`], so a `#[miniextendr]` function returns it
1475/// directly.
1476///
1477/// # GC discipline (rooted by construction, #1750)
1478///
1479/// Every partition is an owned, GC-rooted [`BuiltDataFrame`], so the result can
1480/// be held across R allocations (building another frame, calling back into R)
1481/// before it is returned or converted; there is no convert-immediately
1482/// contract. The [`IntoR`] conversion assembles the named list and releases
1483/// the per-partition roots.
1484pub trait IntoDataFrameSplit: Sized {
1485 /// Partition the rows by variant into one `data.frame` per variant.
1486 fn into_dataframe_split(self) -> DataFrameShape;
1487}
1488
1489/// Rust rows ↔ the pure-Rust columnar companion generated by `#[derive(DataFrameRow)]`.
1490///
1491/// `#[derive(DataFrameRow)]` builds a companion struct (`<Row>DataFrame`) whose fields are
1492/// `Vec`-columns — the in-memory, column-oriented form of `Vec<Row>`. This trait is the
1493/// documented verb surface for that companion: build it from rows (sequentially, or in parallel
1494/// with `feature = "rayon"`) and, for row-iterable companions, read the rows back.
1495///
1496/// It is the pure-Rust complement to [`IntoDataFrame`] / [`FromDataFrame`], which cross the R
1497/// boundary (`Vec<Row>` ↔ R `data.frame`). In particular `from_rows_par`
1498/// (`feature = "rayon"`) builds the **pure-Rust companion** in parallel —
1499/// `IntoDataFrame::into_dataframe_par` cannot, since it yields an R-backed
1500/// [`BuiltDataFrame`] rather than the companion.
1501///
1502/// The derive implements this on the companion type; call `CompanionType::from_rows(rows)`.
1503/// `Row` is a type parameter (not an associated type) so the derive can implement it for a
1504/// `pub` companion even when the row type is private — mirroring `From<Vec<Row>>`, and
1505/// avoiding the private-type-in-public-interface error an associated type would raise.
1506///
1507/// # Reading rows back
1508///
1509/// [`into_rows`](ColumnarFrame::into_rows) is available for **row-iterable** companions
1510/// (named-field structs without column expansion), where it defers to the companion's
1511/// [`IntoIterator`]. Enum and column-expansion companions are write-only in pure Rust; read
1512/// those back across the R boundary via [`FromDataFrame`] or the derive's one-call
1513/// `try_from_dataframe`.
1514pub trait ColumnarFrame<Row>: Sized {
1515 /// Transpose a row vector into the columnar companion (sequential).
1516 fn from_rows(rows: Vec<Row>) -> Self;
1517
1518 /// Parallel transposition (`feature = "rayon"`). Same result as
1519 /// [`from_rows`](ColumnarFrame::from_rows).
1520 ///
1521 /// Defaults to the sequential path; `#[derive(DataFrameRow)]` overrides it with a genuine
1522 /// parallel column fill wherever the row shape allows one: the rows and column values are
1523 /// `Send`, placeholder-filled columns are `Default`, and struct-flattened / `as_list`
1524 /// values are `Clone`. A row shape without these still compiles and gets the sequential
1525 /// path.
1526 #[cfg(feature = "rayon")]
1527 fn from_rows_par(rows: Vec<Row>) -> Self {
1528 Self::from_rows(rows)
1529 }
1530
1531 /// Read the rows back out of the companion.
1532 ///
1533 /// Available for row-iterable companions (named-field structs without column expansion);
1534 /// defers to the companion's [`IntoIterator`]. Enum and column-expansion companions are
1535 /// write-only in pure Rust — read those back via [`FromDataFrame`] / `try_from_dataframe`.
1536 fn into_rows(self) -> Vec<Row>
1537 where
1538 Self: IntoIterator<Item = Row>,
1539 {
1540 self.into_iter().collect()
1541 }
1542}
1543
1544/// The parallel column fill `#[derive(DataFrameRow)]` writes for a companion.
1545///
1546/// The derive implements it only where the row shape allows a parallel fill:
1547/// the rows and every column value can move to another thread (`Send`), and
1548/// what the fill needs of its columns holds (`Default` for a placeholder,
1549/// `Clone` for a value copied out before the rows move). Each of those bounds
1550/// sits behind a higher-ranked binder, so the impl simply does not apply when
1551/// one fails. [`ColumnarFrame::from_rows_par`] then falls back to `from_rows`
1552/// through [`FromRowsParProbe`] instead of failing to compile, so turning on
1553/// `rayon` anywhere in a crate graph never breaks a row type.
1554#[cfg(feature = "rayon")]
1555#[doc(hidden)]
1556pub trait ParallelColumns<Row>: Sized {
1557 /// Fill the companion's columns from the rows in parallel.
1558 fn from_rows_parallel(rows: Vec<Row>) -> Self;
1559}
1560
1561/// Selects the derive's `from_rows_par`: [`ParallelColumns`] when the
1562/// companion implements it, `from_rows` otherwise.
1563///
1564/// The derived override calls
1565/// `(&FromRowsParProbe::<Self, Row>::new()).fill_columns(rows)` with
1566/// [`FromRowsParParallel`] and [`FromRowsParSequential`] in scope. Method
1567/// lookup tries the receiver type `&FromRowsParProbe` first, where only the
1568/// parallel trait's method fits (and only if its impl applies), then
1569/// `&&FromRowsParProbe`, where the sequential one does.
1570#[cfg(feature = "rayon")]
1571#[doc(hidden)]
1572pub struct FromRowsParProbe<Df, Row>(std::marker::PhantomData<fn() -> (Df, Row)>);
1573
1574#[cfg(feature = "rayon")]
1575impl<Df, Row> FromRowsParProbe<Df, Row> {
1576 /// The probe for companion `Df` over `Row`.
1577 #[allow(clippy::new_without_default)]
1578 pub fn new() -> Self {
1579 FromRowsParProbe(std::marker::PhantomData)
1580 }
1581}
1582
1583/// The parallel arm of [`FromRowsParProbe`].
1584#[cfg(feature = "rayon")]
1585#[doc(hidden)]
1586pub trait FromRowsParParallel<Df, Row> {
1587 /// Fill `Df` with [`ParallelColumns::from_rows_parallel`].
1588 fn fill_columns(&self, rows: Vec<Row>) -> Df;
1589}
1590
1591#[cfg(feature = "rayon")]
1592impl<Df: ParallelColumns<Row>, Row> FromRowsParParallel<Df, Row> for FromRowsParProbe<Df, Row> {
1593 fn fill_columns(&self, rows: Vec<Row>) -> Df {
1594 Df::from_rows_parallel(rows)
1595 }
1596}
1597
1598/// The sequential arm of [`FromRowsParProbe`].
1599#[cfg(feature = "rayon")]
1600#[doc(hidden)]
1601pub trait FromRowsParSequential<Df, Row> {
1602 /// Fill `Df` with [`ColumnarFrame::from_rows`].
1603 fn fill_columns(&self, rows: Vec<Row>) -> Df;
1604}
1605
1606#[cfg(feature = "rayon")]
1607impl<Df: ColumnarFrame<Row>, Row> FromRowsParSequential<Df, Row> for &FromRowsParProbe<Df, Row> {
1608 fn fill_columns(&self, rows: Vec<Row>) -> Df {
1609 Df::from_rows(rows)
1610 }
1611}
1612// endregion
1613
1614// region: ColumnSource — internal column-assembly engine (ex-public convert::IntoDataFrame)
1615
1616/// Internal engine that turns a value into a `data.frame`-shaped [`List`].
1617///
1618/// This was the historical public `convert::IntoDataFrame` (`-> List`). It is now an internal
1619/// engine: the public [`IntoDataFrame`] (`-> Result<BuiltDataFrame, _>`) and the enum-flatten
1620/// codegen both delegate to it. Not part of the public verb surface.
1621#[doc(hidden)]
1622pub trait ColumnSource {
1623 /// Convert into a `data.frame`-shaped [`List`] (named columns, `data.frame` class,
1624 /// `row.names`).
1625 fn into_column_list(self) -> List;
1626
1627 /// Extract named column SEXPs from this value.
1628 ///
1629 /// Returns `(name, raw SEXP)` per column. The assembled column list is
1630 /// protected in `scope` before anything is read from it, so every returned
1631 /// SEXP stays reachable (as an element of that list) for as long as `scope`
1632 /// lives, across any number of later allocations (#1748).
1633 ///
1634 /// # Safety
1635 ///
1636 /// Must run on the R main thread, and `scope` must be the innermost live
1637 /// [`ProtectScope`](crate::gc_protect::ProtectScope): its `Drop` unprotects
1638 /// from the top of R's protect stack.
1639 unsafe fn into_named_columns(
1640 self,
1641 scope: &crate::gc_protect::ProtectScope,
1642 ) -> Vec<(String, crate::SEXP)>
1643 where
1644 Self: Sized,
1645 {
1646 use crate::SexpExt as _;
1647 // SAFETY: R main thread and innermost scope (caller contract). Nothing
1648 // allocates between building the list and protecting it.
1649 let sexp = unsafe { scope.protect_raw(self.into_column_list().as_sexp()) };
1650 let n = sexp.len();
1651 let mut out = Vec::with_capacity(n);
1652 let names_sexp = sexp.get_names();
1653 let has_names = !names_sexp.is_nil();
1654 for i in 0..(n as isize) {
1655 let col_sexp = sexp.vector_elt(i);
1656 let col_name = if has_names {
1657 names_sexp.string_elt_str(i).unwrap_or("").to_string()
1658 } else {
1659 i.to_string()
1660 };
1661 out.push((col_name, col_sexp));
1662 }
1663 out
1664 }
1665
1666 /// Assemble this source into a validated [`DataFrame`].
1667 ///
1668 /// The column engine always sets the `data.frame` class (even for an empty frame); the one
1669 /// exception is the unnamed-row degradation, which returns a bare unclassed empty list — the
1670 /// old `panic!("unnamed list elements")` case, now a clean `Err(UnnamedColumns)`.
1671 ///
1672 /// This is the bridge from the internal column-assembly engine to the public [`DataFrame`].
1673 /// We deliberately do **not** offer a blanket `impl<T: ColumnSource> IntoDataFrame for T`:
1674 /// `#[derive(DataFrameRow)]` emits a *concrete* `impl IntoDataFrame for Vec<Row>` per row
1675 /// type (and serde uses the `SerdeRows<T>` newtype), so a generic `for T` blanket would
1676 /// coherence-conflict with every one of those (the compiler treats `Vec<Row>: ColumnSource`
1677 /// as possibly-true). The derive's `into_dataframe` glue calls this method instead.
1678 fn into_dataframe(self) -> Result<DataFrame, DataFrameError>
1679 where
1680 Self: Sized,
1681 {
1682 use crate::SexpExt as _;
1683 let sexp = self.into_column_list().as_sexp();
1684 if !sexp.is_data_frame() {
1685 return Err(DataFrameError::UnnamedColumns);
1686 }
1687 Ok(unsafe { DataFrame::from_built_sexp(sexp) })
1688 }
1689}
1690// endregion
1691
1692// region: rayon-gating shim for #[derive(DataFrameRow)] parallel methods
1693
1694/// Emit the wrapped items only when `miniextendr-api` itself was built with the
1695/// `rayon` feature.
1696///
1697/// `#[derive(DataFrameRow)]` uses this to gate its parallel `*_par` methods on
1698/// **this** crate's `rayon` feature instead of stamping a raw
1699/// `#[cfg(feature = "rayon")]` into the *consumer* crate. A `cfg` inside a
1700/// derive is evaluated against the destination crate, where `rayon` is usually
1701/// not a declared feature — so every downstream package that derives
1702/// `DataFrameRow` without a `rayon` feature of its own trips the
1703/// `unexpected_cfgs` lint (#1117). Routing through this macro moves the `#[cfg]`
1704/// decision into `miniextendr-api`, whose feature set always declares `rayon`,
1705/// so the consumer crate never sees the attribute. The parallel path now
1706/// activates purely on the API crate's `rayon` feature, independent of what the
1707/// consumer names its own.
1708#[doc(hidden)]
1709#[macro_export]
1710#[cfg(feature = "rayon")]
1711macro_rules! __dataframe_row_when_rayon {
1712 ($($item:tt)*) => { $($item)* };
1713}
1714
1715/// No-rayon build: the wrapped parallel methods vanish entirely. The trait's
1716/// `*_par` methods are themselves `#[cfg(feature = "rayon")]`, so there is
1717/// nothing to override.
1718#[doc(hidden)]
1719#[macro_export]
1720#[cfg(not(feature = "rayon"))]
1721macro_rules! __dataframe_row_when_rayon {
1722 ($($item:tt)*) => {};
1723}
1724
1725// endregion
1726
1727// region: DataFrameRowConvert — orphan-rule bridge for `Vec<Row>` conversions
1728
1729/// Row → DataFrame conversion glue emitted by `#[derive(DataFrameRow)]` on the **row type**.
1730///
1731/// The orphan rule forbids the derive from writing `impl IntoDataFrame for Vec<Row>` in the user
1732/// crate: both `IntoDataFrame` and `Vec` are foreign there, and `Row` only appears *covered*
1733/// inside `Vec<_>`, so there is no uncovered local type. Instead the derive implements this
1734/// `#[doc(hidden)]` trait on the local `Row` type (legal — `Row` is local), and `miniextendr_api`
1735/// carries the blanket [`IntoDataFrame`] / [`FromDataFrame`] impls for `Vec<T: DataFrameRowConvert>`
1736/// below (legal — `IntoDataFrame` is local *here*). Users still call the public
1737/// `rows.into_dataframe()?` / `Vec::<Row>::from_dataframe(&df)?` verbs.
1738#[doc(hidden)]
1739pub trait DataFrameRowConvert: Sized {
1740 /// Build a [`DataFrame`] from a row vector (sequential).
1741 fn rows_into_dataframe(rows: Vec<Self>) -> Result<DataFrame, DataFrameError>;
1742
1743 /// Build a [`DataFrame`] from a row vector (parallel; defaults to sequential).
1744 #[cfg(feature = "rayon")]
1745 fn rows_into_dataframe_par(rows: Vec<Self>) -> Result<DataFrame, DataFrameError> {
1746 Self::rows_into_dataframe(rows)
1747 }
1748
1749 /// Read a row vector out of a [`DataFrame`]. `None` means this row shape has no reader
1750 /// (scalar, column-expansion, and struct-flatten struct shapes do; tagged enum shapes with
1751 /// reader-capable fields do too; tagless/map-column/coerced/skip/`as_list` enum shapes and
1752 /// opaque-map shapes do not); the blanket surfaces that as a clear error.
1753 fn rows_from_dataframe(_df: &DataFrame) -> Option<Result<Vec<Self>, DataFrameError>> {
1754 None
1755 }
1756
1757 /// Parallel reader (defaults to the sequential reader).
1758 #[cfg(feature = "rayon")]
1759 fn rows_from_dataframe_par(df: &DataFrame) -> Option<Result<Vec<Self>, DataFrameError>> {
1760 Self::rows_from_dataframe(df)
1761 }
1762}
1763
1764/// Error returned by `Vec::<Row>::from_dataframe` when the row shape has no R→Rust reader.
1765fn no_reader_error() -> DataFrameError {
1766 DataFrameError::Conversion(
1767 "this DataFrameRow shape has no R→Rust reader (struct shapes with scalar/expansion/\
1768 struct-flatten fields do; tagged enum shapes with reader-capable fields do; \
1769 tagless/map-column/coerced/skip/as_list enum shapes and opaque-map shapes do not)"
1770 .to_string(),
1771 )
1772}
1773
1774impl<T: DataFrameRowConvert> IntoDataFrame for Vec<T> {
1775 fn into_dataframe(self) -> Result<BuiltDataFrame, DataFrameError> {
1776 // `rows_into_dataframe` returns the freshly-built frame as a bare view;
1777 // root it immediately (no allocation between the `?` and `adopt`) so the
1778 // returned handle owns its GC root.
1779 // SAFETY: builds SEXPs → runs on the R main thread.
1780 Ok(unsafe { BuiltDataFrame::adopt(T::rows_into_dataframe(self)?) })
1781 }
1782
1783 #[cfg(feature = "rayon")]
1784 fn into_dataframe_par(self) -> Result<BuiltDataFrame, DataFrameError> {
1785 // SAFETY: as in `into_dataframe` above.
1786 Ok(unsafe { BuiltDataFrame::adopt(T::rows_into_dataframe_par(self)?) })
1787 }
1788}
1789
1790impl<T: DataFrameRowConvert> FromDataFrame for Vec<T> {
1791 fn from_dataframe(df: &DataFrame) -> Result<Self, DataFrameError> {
1792 // No input root here: an R-supplied frame is rooted by R's `.Call`
1793 // argument frame, and a Rust-built frame now reaches the reader as a
1794 // borrowed `BuiltDataFrame` (rooted for the borrow) — the handle
1795 // supersedes the old `OwnedProtect` guard (#1128). The reader's own
1796 // sub-frame allocations stay protected by their internal guards.
1797 T::rows_from_dataframe(df).unwrap_or_else(|| Err(no_reader_error()))
1798 }
1799
1800 #[cfg(feature = "rayon")]
1801 fn from_dataframe_par(df: &DataFrame) -> Result<Self, DataFrameError> {
1802 T::rows_from_dataframe_par(df).unwrap_or_else(|| Err(no_reader_error()))
1803 }
1804}
1805
1806/// Row → split-representation glue emitted by `#[derive(DataFrameRow)]` on **enum** row types.
1807///
1808/// Same orphan-rule bridge as [`DataFrameRowConvert`]: the derive cannot write
1809/// `impl IntoDataFrameSplit for Vec<Row>` in the user crate (`Row` is covered by `Vec<_>`), so
1810/// it implements this `#[doc(hidden)]` trait on the local enum type and `miniextendr_api`
1811/// carries the blanket [`IntoDataFrameSplit`] impl for `Vec<T: DataFrameRowSplit>` below.
1812///
1813/// Deliberately a **separate** bridge from [`DataFrameRowConvert`]: the split representation
1814/// only exists for enums, and a method here (even defaulted) would grow the verb onto every
1815/// struct row type. Users call the public `rows.into_dataframe_split()` verb.
1816#[doc(hidden)]
1817pub trait DataFrameRowSplit: Sized {
1818 /// Partition a row vector by variant into one `data.frame` per variant.
1819 fn rows_into_dataframe_split(rows: Vec<Self>) -> DataFrameShape;
1820}
1821
1822impl<T: DataFrameRowSplit> IntoDataFrameSplit for Vec<T> {
1823 fn into_dataframe_split(self) -> DataFrameShape {
1824 T::rows_into_dataframe_split(self)
1825 }
1826}
1827// endregion
1828
1829// region: nrow extraction from row.names
1830
1831/// Extract `nrow` from R's `row.names` attribute.
1832fn extract_nrow(sexp: SEXP) -> Result<usize, DataFrameError> {
1833 let row_names = sexp.get_row_names();
1834
1835 if row_names.is_nil() {
1836 return nrow_from_first_column(sexp);
1837 }
1838
1839 let rn_type = row_names.type_of();
1840 let rn_len = row_names.xlength();
1841
1842 if rn_type == SEXPTYPE::INTSXP && rn_len == 2 {
1843 let rn: &[i32] = unsafe { row_names.as_slice() };
1844 if rn[0].is_na() && rn[1] < 0 {
1845 return Ok((-rn[1]) as usize);
1846 }
1847 }
1848
1849 if let Ok(n) = usize::try_from(rn_len) {
1850 Ok(n)
1851 } else {
1852 Err(DataFrameError::BadRowNames(format!(
1853 "row.names has negative length: {}",
1854 rn_len
1855 )))
1856 }
1857}
1858
1859/// Fall back: extract nrow from the length of the first column.
1860fn nrow_from_first_column(sexp: SEXP) -> Result<usize, DataFrameError> {
1861 let ncol = sexp.xlength();
1862 if ncol == 0 {
1863 return Ok(0);
1864 }
1865 let first_col = sexp.vector_elt(0);
1866 if first_col == SEXP::nil() {
1867 return Ok(0);
1868 }
1869 let len = first_col.xlength();
1870 if let Ok(n) = usize::try_from(len) {
1871 Ok(n)
1872 } else {
1873 Err(DataFrameError::BadRowNames(
1874 "first column has negative length".to_string(),
1875 ))
1876 }
1877}
1878// endregion
1879
1880// region: NamedList / List → DataFrame promotion
1881
1882/// Validate that all columns in a NamedList have equal length, returning the common length.
1883pub(crate) fn validate_equal_lengths(named: &NamedList) -> Result<usize, DataFrameError> {
1884 let list = named.as_list();
1885 let n = list.len();
1886
1887 if n == 0 {
1888 return Ok(0);
1889 }
1890
1891 let first_col = list.as_sexp().vector_elt(0);
1892 let expected: usize = first_col.len();
1893
1894 let names_sexp = list.names();
1895 let mut columns = Vec::new();
1896 for i in 1..n {
1897 let col = list.as_sexp().vector_elt(i);
1898 let col_len: usize = col.len();
1899 if col_len != expected {
1900 let column = if let Some(names) = names_sexp {
1901 // SAFETY: an element of the list's names attribute; NA maps
1902 // to `None`.
1903 unsafe { crate::from_r::charsxp_to_string_lossy(names.string_elt(i)) }
1904 .unwrap_or_else(|| format!("column {}", i))
1905 } else {
1906 format!("column {}", i)
1907 };
1908
1909 columns.push((column, col_len));
1910 }
1911 }
1912
1913 if columns.is_empty() {
1914 Ok(expected)
1915 } else {
1916 Err(DataFrameError::UnequalLengths { expected, columns })
1917 }
1918}
1919
1920impl NamedList {
1921 /// Promote this named list to a [`DataFrame`].
1922 ///
1923 /// Validates equal column lengths, sets the `data.frame` class, and adds compact integer
1924 /// `row.names`.
1925 ///
1926 /// # Errors
1927 ///
1928 /// Returns [`DataFrameError::UnequalLengths`] if columns differ in length.
1929 pub fn as_data_frame(&self) -> Result<BuiltDataFrame, DataFrameError> {
1930 let nrow = validate_equal_lengths(self)?;
1931 self.as_list().set_data_frame_class();
1932 self.as_list().set_row_names_int(nrow);
1933 // SAFETY: R main thread; the list is now a well-formed data.frame VECSXP.
1934 Ok(unsafe { BuiltDataFrame::adopt_sexp(self.as_list().as_sexp()) })
1935 }
1936}
1937
1938impl List {
1939 /// Promote this named list to a [`DataFrame`].
1940 ///
1941 /// # Errors
1942 ///
1943 /// Returns [`DataFrameError`] if the list has no names or columns differ in length.
1944 pub fn as_data_frame(&self) -> Result<BuiltDataFrame, DataFrameError> {
1945 let named = NamedList::new(*self).ok_or(DataFrameError::NoNames)?;
1946 named.as_data_frame()
1947 }
1948}
1949// endregion
1950
1951// region: Debug impl
1952
1953impl std::fmt::Debug for DataFrame {
1954 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1955 f.debug_struct("DataFrame")
1956 .field("nrow", &self.nrow())
1957 .field("ncol", &self.ncol())
1958 .finish()
1959 }
1960}
1961
1962#[cfg(test)]
1963mod tests;
1964// endregion