Skip to main content

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(#[automatically_derived]impl ::core::fmt::Debug for DataFrameError {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        match self {
            Self::NotList(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f,
                    "NotList", &__self_0),
            Self::NotDataFrame =>
                ::core::fmt::Formatter::write_str(f, "NotDataFrame"),
            Self::NoNames => ::core::fmt::Formatter::write_str(f, "NoNames"),
            Self::BadRowNames(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f,
                    "BadRowNames", &__self_0),
            Self::UnequalLengths { expected: __self_0, columns: __self_1 } =>
                ::core::fmt::Formatter::debug_struct_field2_finish(f,
                    "UnequalLengths expected columns", __self_0, &__self_1),
            Self::UnnamedColumns =>
                ::core::fmt::Formatter::write_str(f, "UnnamedColumns"),
            Self::NoSuchColumn(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f,
                    "NoSuchColumn", &__self_0),
            Self::EmptyGroupColumns =>
                ::core::fmt::Formatter::write_str(f, "EmptyGroupColumns"),
            Self::UnsupportedGroupColumn { column: __self_0, type_of: __self_1
                } =>
                ::core::fmt::Formatter::debug_struct_field2_finish(f,
                    "UnsupportedGroupColumn column type_of", __self_0,
                    &__self_1),
            Self::NotGroupedDataFrame =>
                ::core::fmt::Formatter::write_str(f, "NotGroupedDataFrame"),
            Self::GroupsNotDataFrame =>
                ::core::fmt::Formatter::write_str(f, "GroupsNotDataFrame"),
            Self::MissingGroupRows =>
                ::core::fmt::Formatter::write_str(f, "MissingGroupRows"),
            Self::BadGroupRows { group: __self_0, type_of: __self_1 } =>
                ::core::fmt::Formatter::debug_struct_field2_finish(f,
                    "BadGroupRows group type_of", __self_0, &__self_1),
            Self::GroupIndexOutOfRange {
                group: __self_0, value: __self_1, nrow: __self_2 } =>
                ::core::fmt::Formatter::debug_struct_field3_finish(f,
                    "GroupIndexOutOfRange group value nrow", __self_0, __self_1,
                    &__self_2),
            Self::GroupRowUncovered { row: __self_0, nrow: __self_1 } =>
                ::core::fmt::Formatter::debug_struct_field2_finish(f,
                    "GroupRowUncovered row nrow", __self_0, &__self_1),
            Self::GroupRowDuplicated {
                row: __self_0, first_group: __self_1, second_group: __self_2 }
                =>
                ::core::fmt::Formatter::debug_struct_field3_finish(f,
                    "GroupRowDuplicated row first_group second_group", __self_0,
                    __self_1, &__self_2),
            Self::Conversion(__self_0) =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f,
                    "Conversion", &__self_0),
        }
    }
}Debug, #[automatically_derived]impl ::core::clone::Clone for DataFrameError {
    #[inline]
    fn clone(&self) -> Self {
        match self {
            Self::NotList(__self_0) =>
                DataFrameError::NotList(::core::clone::Clone::clone(__self_0)),
            Self::NotDataFrame => DataFrameError::NotDataFrame,
            Self::NoNames => DataFrameError::NoNames,
            Self::BadRowNames(__self_0) =>
                DataFrameError::BadRowNames(::core::clone::Clone::clone(__self_0)),
            Self::UnequalLengths { expected: __self_0, columns: __self_1 } =>
                DataFrameError::UnequalLengths {
                    expected: ::core::clone::Clone::clone(__self_0),
                    columns: ::core::clone::Clone::clone(__self_1),
                },
            Self::UnnamedColumns => DataFrameError::UnnamedColumns,
            Self::NoSuchColumn(__self_0) =>
                DataFrameError::NoSuchColumn(::core::clone::Clone::clone(__self_0)),
            Self::EmptyGroupColumns => DataFrameError::EmptyGroupColumns,
            Self::UnsupportedGroupColumn { column: __self_0, type_of: __self_1
                } =>
                DataFrameError::UnsupportedGroupColumn {
                    column: ::core::clone::Clone::clone(__self_0),
                    type_of: ::core::clone::Clone::clone(__self_1),
                },
            Self::NotGroupedDataFrame => DataFrameError::NotGroupedDataFrame,
            Self::GroupsNotDataFrame => DataFrameError::GroupsNotDataFrame,
            Self::MissingGroupRows => DataFrameError::MissingGroupRows,
            Self::BadGroupRows { group: __self_0, type_of: __self_1 } =>
                DataFrameError::BadGroupRows {
                    group: ::core::clone::Clone::clone(__self_0),
                    type_of: ::core::clone::Clone::clone(__self_1),
                },
            Self::GroupIndexOutOfRange {
                group: __self_0, value: __self_1, nrow: __self_2 } =>
                DataFrameError::GroupIndexOutOfRange {
                    group: ::core::clone::Clone::clone(__self_0),
                    value: ::core::clone::Clone::clone(__self_1),
                    nrow: ::core::clone::Clone::clone(__self_2),
                },
            Self::GroupRowUncovered { row: __self_0, nrow: __self_1 } =>
                DataFrameError::GroupRowUncovered {
                    row: ::core::clone::Clone::clone(__self_0),
                    nrow: ::core::clone::Clone::clone(__self_1),
                },
            Self::GroupRowDuplicated {
                row: __self_0, first_group: __self_1, second_group: __self_2 }
                =>
                DataFrameError::GroupRowDuplicated {
                    row: ::core::clone::Clone::clone(__self_0),
                    first_group: ::core::clone::Clone::clone(__self_1),
                    second_group: ::core::clone::Clone::clone(__self_2),
                },
            Self::Conversion(__self_0) =>
                DataFrameError::Conversion(::core::clone::Clone::clone(__self_0)),
        }
    }
}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) => f.write_fmt(format_args!("expected a data frame, got {0}",
        crate::typed_list::sexptype_name(*actual)))write!(
156                f,
157                "expected a data frame, got {}",
158                crate::typed_list::sexptype_name(*actual)
159            ),
160            DataFrameError::NotDataFrame => f.write_fmt(format_args!("object does not inherit from data.frame"))write!(f, "object does not inherit from data.frame"),
161            DataFrameError::NoNames => f.write_fmt(format_args!("data.frame has no column names"))write!(f, "data.frame has no column names"),
162            DataFrameError::BadRowNames(msg) => {
163                f.write_fmt(format_args!("could not extract nrow from row.names: {0}", msg))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                        f.write_fmt(format_args!("; "))write!(f, "; ")?;
169                    }
170                    f.write_fmt(format_args!("column {0:?} has length {1} (expected {2})", column,
        actual, expected))write!(
171                        f,
172                        "column {column:?} has length {actual} (expected {expected})"
173                    )?;
174                }
175                Ok(())
176            }
177            DataFrameError::UnnamedColumns => {
178                f.write_fmt(format_args!("cannot create data frame from unnamed list elements"))write!(f, "cannot create data frame from unnamed list elements")
179            }
180            DataFrameError::NoSuchColumn(name) => {
181                f.write_fmt(format_args!("no such column: {0:?}", name))write!(f, "no such column: {:?}", name)
182            }
183            DataFrameError::EmptyGroupColumns => {
184                f.write_fmt(format_args!("group_by_multi requires at least one column"))write!(f, "group_by_multi requires at least one column")
185            }
186            DataFrameError::UnsupportedGroupColumn { column, type_of } => f.write_fmt(format_args!("cannot group by column {0:?} ({1}): supported key types are factor, character, integer, logical, and double (including Date and POSIXct)",
        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 => f.write_fmt(format_args!("not a grouped_df: the frame does not inherit from grouped_df or rowwise_df; use group_by/group_by_multi to compute grouping instead"))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 => f.write_fmt(format_args!("not a valid grouped_df or rowwise_df: the `groups` attribute must be a data frame. {0}",
        CORRUPT_GROUPS_HINT))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 => f.write_fmt(format_args!("not a valid grouped_df or rowwise_df: the last column of the `groups` attribute must be called `.rows`. {0}",
        CORRUPT_GROUPS_HINT))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            } => f.write_fmt(format_args!("not a valid grouped_df or rowwise_df: the `.rows` column must be a list of one-based integer vectors, not {0}. {1}",
        type_of, CORRUPT_GROUPS_HINT))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            } => f.write_fmt(format_args!("not a valid grouped_df or rowwise_df: the `.rows` column must be a list of one-based integer vectors, but the element for group {0} is {1}. {2}",
        group + 1, type_of, CORRUPT_GROUPS_HINT))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 } => f.write_fmt(format_args!("grouped_df `.rows` index {0} for group {1} is out of range (the frame has {2} rows; valid indices are 1..={3}). {4}",
        value, group + 1, nrow, nrow, STALE_GROUPS_HINT))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 } => f.write_fmt(format_args!("grouped_df `.rows` do not cover row {0} (the frame has {1} rows; each row belongs to exactly one group). {2}",
        row + 1, nrow, STALE_GROUPS_HINT))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 => f.write_fmt(format_args!("grouped_df `.rows` list row {0} twice in group {1} (each row belongs to exactly one group). {2}",
        row + 1, first_group + 1, STALE_GROUPS_HINT))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            } => f.write_fmt(format_args!("grouped_df `.rows` put row {0} in both group {1} and group {2} (each row belongs to exactly one group). {3}",
        row + 1, first_group + 1, second_group + 1, STALE_GROUPS_HINT))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) => f.write_fmt(format_args!("{0}", 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(#[automatically_derived]#[doc(hidden)]unsafe impl ::core::clone::TrivialClone
    for DataFrame {
}
#[automatically_derived]impl ::core::clone::Clone for DataFrame {
    #[inline]
    fn clone(&self) -> Self {
        let _: ::core::clone::AssertParamIsClone<SEXP>;
        *self
    }
}Clone, #[automatically_derived]impl ::core::marker::Copy for DataFrame { }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| !#[allow(non_exhaustive_omitted_patterns)] match col_name(class, i) {
    Some("grouped_df" | "rowwise_df") => true,
    _ => false,
}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(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("row.names has negative length: {0}",
                rn_len))
    })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(|| ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("column {0}", i))
    })format!("column {}", i))
1905            } else {
1906                ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("column {0}", i))
    })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