Home / Guides / Features

Features

Cargo features, derive macros, and optional subsystems

3 min read 466 words

🔗Optional Cargo Features

miniextendr-api gates optional functionality behind Cargo feature flags. Only the default feature (doc-lint) is enabled automatically.

Add features to the miniextendr-api dependency in your package’s Cargo.toml:

[dependencies]
miniextendr-api = { version = "0.1", features = ["rayon", "serde", "ndarray"] }

The prelude re-exports upstream crates for every enabled feature, so you rarely need to add optional crates as separate direct dependencies.

🔗Categories at a glance

CategoryFeatures
Core / Rnonapi, rayon, worker-thread, connections, indicatif, vctrs
Serializationserde, serde_json, toml
Matrix / Arrayndarray, nalgebra
Numericnum-bigint, rust_decimal, ordered-float, num-complex
Adaptersnum-traits, bytes
String / Textuuid, regex, url, aho-corasick
Date / Timetime
RNGrand, rand_distr
Collectionsindexmap, tinyvec
Eithereither
Binaryborsh, raw_conversions
Hashingsha2
Bitflagsbitflags, bitvec
Formattingtabled
Arrow / DataFusionarrow, datafusion
Logginglog
Project defaultsstrict-default, coerce-default, r6-default, s7-default, worker-default
Diagnosticsmacro-coverage, growth-debug

For the complete entry-by-entry reference – including descriptions, type tables, and code examples for every feature – see the Feature Flags Reference in the manual.

🔗Derive Macros

miniextendr ships roughly twenty derives grouped by what they produce.

🔗Wrapper types

DerivePurpose
#[derive(ExternalPtr)]Wrap struct as an EXTPTRSXP; implements TypedExternal and IntoExternalPtr
#[derive(RNativeType)]Newtype wrapper around a native R scalar (i32, f64, bool, String, etc.)

🔗ALTREP

Typed derives generate the full ALTREP class from field attributes. The manual Altrep derive lets you implement the per-method traits yourself.

DerivePurpose
#[derive(AltrepInteger)]Integer ALTREP class from #[altrep(len, elt, class, ...)] fields
#[derive(AltrepReal)]Real (double) ALTREP class
#[derive(AltrepLogical)]Logical ALTREP class
#[derive(AltrepRaw)]Raw (byte) ALTREP class
#[derive(AltrepString)]Character ALTREP class (Vec<Option<String>> preserves NA_character_)
#[derive(AltrepComplex)]Complex ALTREP class
#[derive(AltrepList)]List ALTREP class
#[derive(Altrep)]Manual pattern – registers the class; you implement AltrepLen and Alt*Data

🔗List / data-frame round-tripping

DerivePurpose
#[derive(IntoList)]Convert struct to a named R list
#[derive(TryFromList)]Convert named R list to struct
#[derive(DataFrameRow)]Treat struct as a data-frame row; generates a companion DataFrame type
#[derive(Vctrs)]vctrs-compatible S3 vector class (Vctr, Rcrd, ListOf kinds)

🔗Enums to R

DerivePurpose
#[derive(RFactor)]Map enum variants to R factor levels
#[derive(MatchArg)]Map enum variants to R character values via match.arg

🔗Conversion preference

Control which IntoR / TryFromSexp path a type takes when multiple are possible.

DerivePurpose
#[derive(PreferExternalPtr)]Prefer ExternalPtr wrapping
#[derive(PreferList)]Prefer named-list representation
#[derive(PreferRNativeType)]Prefer native R scalar representation

🔗Attribute Options

The #[miniextendr] attribute supports many options:

// Function-level
#[miniextendr]                       // Basic export
#[miniextendr(strict)]               // Reject lossy conversions
#[miniextendr(internal)]             // @keywords internal
#[miniextendr(noexport)]             // Suppress @export
#[miniextendr(unwrap_in_r)]          // Return Result errors as R values
#[miniextendr(default = "value")]    // Default parameter value

// Impl-level (class systems)
#[miniextendr]                       // Env style (default)
#[miniextendr(r6)]                   // R6 class
#[miniextendr(s3)]                   // S3 methods
#[miniextendr(s4)]                   // S4 class
#[miniextendr(s7)]                   // S7 class

🔗Variadic Arguments (Dots)

R’s ... becomes &Dots in Rust:

#[miniextendr]
pub fn count_args(args: ...) -> i32 {
    args.len() as i32
}

Validate dot structure with typed_list!. Write _: ... for dots the body doesn’t read by name:

#[miniextendr(dots = typed_list!(x => integer(), y => numeric()))]
pub fn structured_dots(_: ...) -> f64 {
    let x: i32 = dots_typed.get("x").expect("x");
    let y: f64 = dots_typed.get("y").expect("y");
    f64::from(x) + y
}

🔗Factors (Enums)

Map Rust enums to R factors:

#[derive(miniextendr_api::RFactor)]
pub enum Color { Red, Green, Blue }

#[miniextendr]
pub fn describe_color(color: Color) -> &'static str {
    match color {
        Color::Red => "warm",
        Color::Green | Color::Blue => "cool",
    }
}

🔗Full reference

This page is a curated entry point. See the user manual for the exhaustive treatment, edge cases, and every feature switch.

Back to Guides