Struct BuiltDataFrame 

pub struct BuiltDataFrame {
    view: DataFrame,
    root: Preserved,
}

An owned, GC-rooted data.frame built on the Rust side.

DataFrame is a cheap Copy view over a bare SEXP with no root of its own — sound only while something else keeps the SEXP reachable (an R .Call argument frame roots R-supplied frames; a surrounding ProtectScope roots transients). A frame that Rust constructs has no such external root, so holding the bare view across any R allocation is a latent use-after-free (issue #1128): the GC reclaims the frame, and a freed-but-intact read passes tests silently until the slot is reused.

BuiltDataFrame is the return type of every Rust-side constructor (IntoDataFrame::into_dataframe, SerdeRowBuilder::finish, DataFrame::builder().build(), the serde *_to_dataframe verbs, NamedList::as_data_frame), and the partition type inside the split verbs’ DataFrameShape (IntoDataFrameSplit::into_dataframe_split, #1750; the serde vec_to_dataframe_split / result_to_dataframe, #1265). It roots the frame with a Preserved handle (R_PreserveObject on construction, R_ReleaseObject on drop), so holding it across allocations is safe by construction. It Derefs to DataFrame, so every read/edit method keeps working unchanged; hand the frame back to R with IntoR::into_sexp — or just return it from a #[miniextendr] fn, which converts it through IntoR transparently.

Not Copy/Clone (each root is released exactly once) and not Send (R’s precious list is R-main-thread state).

Editing (chains stay rooted, #1247)

The new-frame editing methods (DataFrame::drop, DataFrame::select, DataFrame::select_rows, DataFrame::prepend_column, DataFrame::with_column) also return BuiltDataFrame, and this type carries inherent forwards for the whole editing set, so rows.into_dataframe()?.drop("x").select(&["y"]) is rooted at every link.

Residual

The cheap view can still be smuggled across allocations by hand: dereferencing (*built) copies out an unrooted DataFrame view that dangles once the handle drops. That is an opt-in footgun, not the constructor/editing path this type makes safe.

Fields

view: DataFrame

root: Preserved

Roots view’s frame for as long as the handle lives.

Implementations

impl BuiltDataFrame

pub unsafe fn adopt_sexp(sexp: SEXP) -> Self

Root an already-built data.frame SEXP and take ownership of the root.

Safety

Must run on the R main thread. sexp must be a well-formed data.frame VECSXP. Rooting is immediate (see Preserved::new), so a freshly-assembled unprotected SEXP is safe to pass directly.

pub unsafe fn adopt(df: DataFrame) -> Self

Root a DataFrame view, taking ownership of a fresh root.

Rooting an already-rooted frame is sound: R_PreserveObject entries stack (the precious list is a cons list, duplicates allowed), and each BuiltDataFrame releases exactly the one entry it added.

Safety

Must run on the R main thread. df must wrap a well-formed, still-live data.frame VECSXP (reachable at the moment of the call).

pub(crate) unsafe fn from_root(root: Preserved) -> Self

Take over an existing root of a frame.

Safety

root holds a well-formed data.frame VECSXP.

pub fn drop(self, col: &str) -> BuiltDataFrame

Remove a column by name — see DataFrame::drop.

Inherent forward: consumes this handle and returns the rooted result.

pub fn select(self, cols: &[&str]) -> BuiltDataFrame

Keep only the named columns — see DataFrame::select.

pub fn select_rows(&self, idx: &[usize]) -> BuiltDataFrame

Keep only the given rows — see DataFrame::select_rows.

pub fn prepend_column(self, name: &str, column: SEXP) -> BuiltDataFrame

Insert a column at index 0 — see DataFrame::prepend_column.

column must be kept reachable by the caller across this call.

pub fn with_column(self, name: &str, column: SEXP) -> BuiltDataFrame

Upsert a column — see DataFrame::with_column.

column must be kept reachable by the caller across this call.

pub fn rename(self, from: &str, to: &str) -> BuiltDataFrame

Rename a column — see DataFrame::rename.

In-place edit of the same frame: this handle (and its root) carries straight through.

pub fn strip_prefix(self, prefix: &str) -> BuiltDataFrame

Strip a prefix from column names — see DataFrame::strip_prefix.

In-place edit of the same frame: this handle (and its root) carries straight through.

Methods from Deref<Target = DataFrame>

pub fn group_by(&self, col: &str) -> Result<GroupedDataFrame, DataFrameError>

Partition this frame’s rows by the values of the named column.

Computes group indices in a single pass on the main thread. Supported key columns: factor (fast path — levels are the keys, level order kept, empty levels included), character, integer, logical, and double (Date and POSIXct included; keyed as GroupKey::Real, labelled by R’s as.character()). List columns and bit64 integer64 columns are an error.

NA keys form one group, ordered last (unlike R split(), which drops NA-keyed rows). See the module docs for the full key semantics.

pub fn group_by_multi( &self, cols: &[&str], ) -> Result<GroupedDataFrame, DataFrameError>

Partition this frame’s rows by a composite key over several columns — the multi-column analogue of group_by.

Each supported column contributes one scalar key per row (factor level, character, integer, logical, or double — same rules and errors as group_by); the per-row keys are zipped into a GroupKey::Tuple in column order.

Order

Non-NA groups match split(df, interaction(col1, col2, …, drop = TRUE)): the first column varies fastest (R interaction()’s default, lex.order = FALSE), each column ordered as group_by would order it alone (factor level order, byte-sorted characters, numeric integers and doubles — NaN after every number — and FALSE then TRUE). For character keys the match is exact for keys whose byte order coincides with the session’s collation — always true in the C locale; single-case ASCII in practice (e.g. en_US.UTF-8 collates a A b B where byte order gives A B a b). This is inherited from group_by’s byte-order choice for character keys — see the group-order note in the module docs.

NA

interaction() maps any row with an NA in any component to NA and split() drops it. This method instead keeps such rows: every distinct NA-containing tuple forms its own group, all ordered after the non-NA groups, in first-encounter row order. This extends the single-column NA-last convention (see the module docs).

Slice

An empty slice is an error. A single-column slice delegates to group_by and yields scalar keys (not 1-tuples), so callers never have to special-case one-element tuples.

pub fn group_declaration( &self, ) -> Result<Option<GroupDeclaration>, DataFrameError>

Read a dplyr-grouped frame’s grouping declaration — its grouping variables and .drop policy — without its cached group rows.

Returns what dplyr’s group_vars() and group_by_drop_default() report: Ok(None) when the frame is not grouped, and an error when it is grouped but its groups attribute is corrupt, where group_vars() errors too (see below). Nothing is partitioned and no row index is read, so the key-column types and whether the cached .rows still fit the frame never matter. A function that groups the frame’s current rows itself (e.g. with group_by_multi over GroupDeclaration::vars) reads this instead of group_by_metadata, which trusts the cached rows.

Grouped frames

A frame is grouped when it inherits from grouped_df or rowwise_df, whatever its attributes: dplyr::is_grouped_df() is inherits(x, "grouped_df"). A plain data.frame with a stray groups attribute is not grouped (Ok(None)).

Errors

A grouped frame’s groups attribute must pass the structural checks of dplyr’s validate_grouped_df(), which group_vars() runs on a grouped_df: it is a data frame (GroupsNotDataFrame), its last column is called .rows (MissingGroupRows), and that column is a list of integer vectors (BadGroupRows; a list of doubles is rejected, as in dplyr). The row indices themselves are not checked, as group_vars() does not check them either, so stale .rows after a subset still yield the declaration.

A rowwise_df gets the same checks. dplyr is looser here: group_vars() reads a rowwise_df’s groups attribute without validating it. validate_rowwise_df() applies the same checks, plus row-shape checks that this method skips (one .rows element per row, each holding its own row number).

Example

// df arrived as dplyr::group_by(data, site, .drop = FALSE)
let decl = df.group_declaration()?.expect("a grouped_df");
assert_eq!(decl.vars, ["site"]);
assert!(!decl.drop);

pub fn group_by_metadata(&self) -> Result<GroupedDataFrame, DataFrameError>

Ingest a dplyr grouped_df’s existing grouping from its groups attribute — honoring the caller’s grouping without recomputing it.

dplyr stores a grouped_df’s grouping in attr(df, "groups"): a data.frame whose leading columns are the group-key columns (one row per group, in dplyr’s group order) and whose trailing .rows list-column holds, per group, the 1-based row indices into df. This method reads that metadata verbatim into a GroupedDataFrame — the same type group_by / group_by_multi produce — so a #[miniextendr] function handed a dplyr-grouped frame can respect the caller’s grouping, including multi-column groupings.

Unlike group_by, this does no recomputation: a frame that is not grouped (see group_declaration for the test) is an error (NotGroupedDataFrame). Callers who want the framework to compute grouping should use group_by / group_by_multi.

Keys

A single key column yields scalar GroupKeys; multiple key columns yield GroupKey::Tuples (labels .-joined), consistent with group_by_multi. Supported key-column types are the same as group_by (factor, character, integer, logical, double — Date and POSIXct included); a list / integer64 key column is an error.

Order & empty groups

The groups-frame row order is preserved verbatim — dplyr’s order is authoritative, with no re-sorting and no NA reordering. .drop = FALSE empty groups (zero-length .rows) are kept as groups with empty index vectors, mirroring the empty-factor-level convention of group_by.

Trusts the cached rows

The .rows are dplyr’s cache of the grouping, and this method uses them as they are. It checks that they still fit the frame — every index in 1..=nrow, every row in exactly one group — and reports stale metadata otherwise (GroupIndexOutOfRange, GroupRowUncovered, GroupRowDuplicated). The usual cause is subsetting a grouped frame without dplyr loaded: [ then keeps the old groups attribute. It does not compare the rows’ key values with their group’s key, so a pure reorder done the same way (df[c(3, 4, 1, 2), ]) still fits and yields the old row positions (#1687). To group the current rows instead, read the declaration with group_declaration and group by its variables.

Errors

NotGroupedDataFrame (not grouped); for a corrupt groups attribute, the errors group_declaration reports (GroupsNotDataFrame, MissingGroupRows, BadGroupRows: .rows must be a list of integer vectors, so a list of doubles is rejected, as in dplyr); UnequalLengths (a key column’s length differs from that of .rows); UnsupportedGroupColumn (a key column of an unsupported type); or one of the stale-metadata errors above. Every .rows index is converted from R’s 1-based to 0-based.

GC

The groups attribute frame (and its columns) is only read here, during construction; it stays reachable via self’s attribute pairlist — which R protects as a .Call argument frame for the duration of the call — so it needs no separate root. Only the returned GroupedDataFrame roots the source frame for its own lifetime (see its GC-rooting docs).

fn groups_attr(&self) -> Result<Option<GroupsAttr>, DataFrameError>

The groups attribute of a dplyr-grouped frame, checked the way dplyr’s validate_grouped_df() checks it (with its default check_bounds = FALSE).

Ok(None) when the frame inherits from neither grouped_df nor rowwise_df. Otherwise the attribute must be a data frame with at least one column (DataFrameError::GroupsNotDataFrame), whose last column is called .rows (DataFrameError::MissingGroupRows) and is a list of integer vectors (DataFrameError::BadGroupRows). These are dplyr’s tests: inherits(groups, "data.frame") with at least one column, the last name, typeof(.rows) == "list", and every element’s typeof() == "integer". .rows and the key columns are read by position, so a column named .rows elsewhere in the frame is not mistaken for it.

pub fn column<T>(&self, name: &str) -> Option<T>

where T: TryFromSexp,

Get a column by name, converting to type T.

Returns None if the column name is not found or conversion fails.

T may be a vector/collection target (Vec<f64>, Vec<i32>, Vec<String>, …) — the natural shape for a column — or a scalar for a length-1 column. The conversion error is discarded (that is what makes this return Option), so T::Error is unconstrained; use column_raw when you need the error.

pub fn column_index<T>(&self, idx: usize) -> Option<T>

where T: TryFromSexp,

Get a column by 0-based index, converting to type T.

As with column, T may be a vector/collection or a scalar target type; the conversion error is discarded.

pub fn column_raw(&self, name: &str) -> Option<SEXP>

Get the raw SEXP for a column by name.

pub fn nrow(&self) -> usize

Number of rows.

pub fn ncol(&self) -> usize

Number of columns.

pub fn names(&self) -> Vec<String>

Collect column names in column order.

pub fn contains_column(&self, name: &str) -> bool

Check whether a column name exists.

pub fn validate( &self, spec: &TypedListSpec, ) -> Result<TypedList, TypedListError>

Validate the data frame’s column types against a TypedListSpec.

pub fn as_list(&self) -> List

Get the underlying List.

pub fn as_sexp(&self) -> SEXP

Get the underlying SEXP.

fn named_list(&self) -> NamedList

Build the NamedList index for O(1) column-by-name access.

pub fn rename(self, from: &str, to: &str) -> Self

Rename a column. No-op if from doesn’t match any column name.

In-place edit of the names attribute — returns the same frame (and therefore inherits whatever root the input already had), unlike the new-frame producers (drop and friends), which return a rooted BuiltDataFrame. On a BuiltDataFrame receiver the inherent forward (BuiltDataFrame::rename) keeps the handle instead.

Other attributes are untouched, so renaming a grouping column of a dplyr grouped_df leaves its groups naming the old column (#1702).

pub fn strip_prefix(self, prefix: &str) -> Self

Strip a prefix from all column names that start with it.

In-place edit of the names attribute — returns the same frame; see rename’s rooting note.

pub fn drop(self, col: &str) -> BuiltDataFrame

Remove a column by name. No-op if the column doesn’t exist.

Frame attributes

The new frame keeps every attribute of the input except names: its class, row.names, and anything else on the frame (a units map, a package’s metadata), as dplyr::select() and tibble’s [ do. This holds for every column producer (select, prepend_column, with_column).

A dplyr grouped_df / rowwise_df keeps its grouping while every grouping column is still there, unchanged. Removing or replacing one returns the ungrouped frame instead (no groups attribute, no grouped_df / rowwise_df class), where dplyr’s [ would regroup by the grouping columns that remain.

Rooting

Returns an owned, GC-rooted BuiltDataFrame (#1247): the result frame is rooted before this method returns, so holding it across R allocations is safe by construction. The no-op path re-roots the input frame (each BuiltDataFrame releases exactly its own root — R_PreserveObject entries stack, so re-rooting an already-rooted SEXP is sound).

The input view must be reachable when calling (the usual DataFrame view contract: an R .Call argument frame, a ProtectScope, or a live BuiltDataFrame).

pub fn select(self, cols: &[&str]) -> BuiltDataFrame

Keep only the named columns, in the order given. Unknown names are skipped.

Keeps the frame’s attributes and, while every grouping column is selected, its dplyr grouping; see drop’s frame-attribute note.

Rooting

Returns an owned, GC-rooted BuiltDataFrame — see drop’s rooting note (#1247).

pub fn select_rows(&self, idx: &[usize]) -> BuiltDataFrame

Keep only the rows at the given 0-based indices, in order.

Subsets every column to the specified rows and rebuilds compact integer row.names. Used by the enum reader to densify a flattened sub-frame before recursing into the inner type’s reader, and by group iteration.

A row is a row of every column, as in df[idx, , drop = FALSE]:

• A vector or list column is gathered by element, and its element names, if any, are subset with the values.
• A column with a dim (an I(matrix) column, or an array) is gathered along its first dimension: dim becomes c(length(idx), dim[-1]) and the first dimnames component (the row names) is subset, the rest kept. Arrays of three or more dimensions follow vctrs::vec_slice() here; base [.data.frame subsets those by element.
• A data.frame column (a packed column) is subset the same way, recursively.

Each column keeps all of its other attributes (SexpExt::copy_most_attrib, the vctrs::vec_slice() rule), so a POSIXct column keeps its tzone, a difftime its units and an I() column its AsIs class.

Frame attributes

The new frame keeps every attribute of the input frame except names (the columns’ names, as before) and row.names (fresh, 1:length(idx)): its class, and anything else on the frame, such as a units map describing some columns or a package’s metadata. This is what dplyr::slice() (dplyr_row_slice() / dplyr_reconstruct()), vctrs::vec_slice(), tibble’s [ and base [.data.frame keep on a row subset. A packed data.frame column keeps its own the same way.

dplyr’s grouping does not survive. A grouped_df or rowwise_df caches each group’s row indices in its groups attribute, which no longer matches the selected rows, so the result has no groups attribute and no grouped_df / rowwise_df class: it is the ungrouped frame (a tibble, for a dplyr input). dplyr::slice() recomputes the groups instead. To keep the grouping, read it from the input with group_declaration and regroup the result, in Rust with group_by_multi over its vars, or in R with dplyr::grouped_df(out, dplyr::group_vars(df)).

Any other attribute indexed by row is copied as it is. A package that keeps one must rebuild it after a row subset, as dplyr’s extension guide (?dplyr_row_slice) asks of dplyr_row_slice() methods.

PROTECT discipline

Allocates new column vectors (and dim / dimnames for matrix columns) while the output list is OwnedProtected, rooting each new column in it before the next allocation.

Rooting

Returns an owned, GC-rooted BuiltDataFrame — see drop’s rooting note (#1247).

pub fn prepend_column(self, name: &str, column: SEXP) -> BuiltDataFrame

Insert a column at index 0 (leftmost), removing any same-named column first.

Keeps the frame’s attributes and its dplyr grouping, unless name replaces a grouping column; see drop’s frame-attribute note.

Rooting

Returns an owned, GC-rooted BuiltDataFrame — see drop’s rooting note (#1247). column must be kept reachable by the caller (e.g. under an OwnedProtect) across this call — the new frame is allocated before column is stored into it.

pub fn with_column(self, name: &str, column: SEXP) -> BuiltDataFrame

Upsert a column: replace the column named name if it exists, else append.

The append path builds a new frame that keeps the input’s attributes and dplyr grouping (see drop’s frame-attribute note). The replace path stores column into the input frame itself and returns that frame, attributes untouched, so replacing a grouping column leaves dplyr’s groups stale (#1702).

Rooting

Both paths return an owned, GC-rooted BuiltDataFrame (#1247) — the in-place replace path re-roots the same frame it received (sound: R_PreserveObject entries stack; this handle releases exactly one). column must be kept reachable by the caller across this call — the append path allocates the new frame before column is stored into it.

Trait Implementations

impl Debug for BuiltDataFrame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for BuiltDataFrame

type Target = DataFrame

The resulting type after dereferencing.

fn deref(&self) -> &DataFrame

Dereferences the value.

impl IntoR for BuiltDataFrame

Releases the root and hands the frame over, unprotected, as DataFrame::as_sexp / IntoR::into_sexp do: the caller (typically the .Call return path) takes over protection. R_ReleaseObject does not allocate, so no GC can run between the release and the return.

type Error = !

The error type for fallible conversions.

fn try_into_sexp(self) -> Result<SEXP, Self::Error>

Try to convert this value to an R SEXP.

unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error>

Try to convert to SEXP without thread safety checks.

fn into_sexp(self) -> SEXP

Convert this value to an R SEXP, panicking on error.

unsafe fn into_sexp_unchecked(self) -> SEXP

where Self: Sized,

Convert to SEXP without thread safety checks, panicking on error.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 16 bytes