Struct DataFrame 

pub struct DataFrame {
    sexp: SEXP,
}

An owned, validated R data.frame. The data-frame type.

Wraps a built VECSXP carrying the data.frame class + row.names. A single coherent type for building (Rust → R), reading (R → Rust), and post-assembly editing — replacing the historical row-buffer / built-SEXP / read-wrapper trio with one coherent type.

Building

Prefer the IntoDataFrame trait on your data:

let df: DataFrame = 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.

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<Error = SexpError>,

Get a column by name, converting each element to type T.

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

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

where T: TryFromSexp<Error = SexpError>,

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

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.

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

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

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

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

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

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

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

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.

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

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

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

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

pub fn builder(nrow: usize) -> RDataFrameBuilder

Start a closure-per-column builder yielding a DataFrame.

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