Struct DataFrame 

pub struct DataFrame {
    sexp: SEXP,
}

A cheap Copy view over a validated R data.frame.

The view carries no GC root. It is sound while an R .Call argument frame, a ProtectScope, or an owning BuiltDataFrame keeps the SEXP reachable. Rust-side constructors never return this bare view; they return BuiltDataFrame.

Building

Prefer the IntoDataFrame trait on your data (it returns an owned, GC-rooted BuiltDataFrame that Derefs to DataFrame):

let df = rows.into_dataframe()?;

or the closure-fill DataFrame::builder for heterogeneous parallel column fill (feature = "rayon").

Reading

Wrap an incoming SEXP with DataFrame::from_sexp (or accept DataFrame directly as a #[miniextendr] argument), then pull typed columns with DataFrame::column, or deserialize whole rows with FromDataFrame.

Fields

sexp: SEXP

Implementations

impl 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, and logical. Double columns error — cut() or factor() the column in R first.

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, or logical — 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, 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_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 plain (non-grouped) data.frame 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); a double / list 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.

Errors

NotGroupedDataFrame (no groups attribute / not a data.frame), MissingGroupRows (no .rows column), BadGroupRows (a .rows element is not an integer/integerish vector), or GroupIndexOutOfRange (a .rows index is < 1 or > nrow). 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).

impl DataFrame

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

Wrap an already-built data.frame SEXP without re-validation.

Used by the column assemblers, which produce a well-formed data.frame by construction.

Safety

sexp must be a VECSXP with the data.frame class and consistent row.names.

pub fn from_sexp(sexp: SEXP) -> Result<Self, DataFrameError>

Wrap an existing R data.frame SEXP, validating it.

Validates that the object:

1. Is a VECSXP (list)
2. Inherits from "data.frame"
3. Has a names attribute
4. Has extractable row.names for nrow

Errors

Returns DataFrameError if validation fails.

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.

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.

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.

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 (each a vector or list-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.

PROTECT discipline

Allocates one new column vector per column — OwnedProtects the output list across the loop so previously-built column SEXPs survive subsequent allocations.

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.

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.

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.

pub fn builder(nrow: usize) -> RDataFrameBuilder

Start a closure-per-column builder yielding a rooted BuiltDataFrame.

The heterogeneous-column analogue of with_r_matrix: each column buffer is R memory filled by a per-column closure. Available regardless of the rayon feature (#1055); the columns are filled in parallel when rayon is enabled and serially otherwise — the resulting data.frame is identical either way.

let df = DataFrame::builder(1000)
    .column::<f64>("x", |chunk, off| for (i, v) in chunk.iter_mut().enumerate() { *v = (off + i) as f64 })
    .column_str("label", |i| Some(format!("row{i}")))
    .build();

Trait Implementations

impl Clone for DataFrame

fn clone(&self) -> DataFrame

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for DataFrame

impl Debug for DataFrame

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

Formats the value using the given formatter.

impl IntoR for DataFrame

type Error = Infallible

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.

impl TrivialClone for DataFrame

impl TryFromSexp for DataFrame

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

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: 8 bytes