miniextendr_api/

optionals.rs

//! Optional feature integrations with third-party crates.
//!
//! This module contains all feature-gated integrations with external crates.
//! Each submodule is only compiled when its corresponding feature is enabled.
//!
//! # Available Features
//!
//! | Feature | Module | Description |
//! |---------|--------|-------------|
//! | `rayon` | `rayon_bridge` | Parallel computation with R interop |
//! | `rand` | `rand_impl` | R's RNG wrapped for `rand` crate |
//! | `rand_distr` | - | Re-exports `rand_distr` distributions |
//! | `either` | `either_impl` | `Either<L, R>` conversions |
//! | `ndarray` | `ndarray_impl` | N-dimensional array conversions |
//! | `nalgebra` | `nalgebra_impl` | Linear algebra type conversions |
//! | `num-bigint` | `num_bigint_impl` | Big integer support |
//! | `rust_decimal` | `rust_decimal_impl` | Decimal number support |
//! | `ordered-float` | `ordered_float_impl` | Ordered floats for sorting |
//! | `uuid` | `uuid_impl` | UUID conversions |
//! | `regex` | `regex_impl` | Compiled regex from R strings |
//! | `indexmap` | `indexmap_impl` | Order-preserving maps |
//! | `time` | `time_impl` | Date/time conversions |
//! | `jiff` | `jiff_impl` | Date/time conversions with IANA tz (parallel to `time`) |
//! | `serde` | `serde_impl` | JSON serialization |
//! | `num-traits` | `num_traits_impl` | Generic numeric operations |
//! | `bytes` | `bytes_impl` | Byte buffer operations |
//! | `num-complex` | `num_complex_impl` | Complex number support |
//! | `url` | `url_impl` | URL parsing and validation |
//! | `sha2` | `sha2_impl` | Cryptographic hashing |
//! | `blake3` | `blake3_impl` | BLAKE3 hashing |
//! | `md5` | `md5_impl` | MD5 hashing (interop only — broken crypto) |
//! | `globset` | `globset_impl` | Shell-style glob matching |
//! | `zstd` | `zstd_impl` | zstd compression |
//! | `bitflags` | `bitflags_impl` | Bitflag conversions |
//! | `bitvec` | `bitvec_impl` | Bit vector conversions |
//! | `aho-corasick` | `aho_corasick_impl` | Multi-pattern string search |
//! | `toml` | `toml_impl` | TOML parsing |
//! | `tabled` | `tabled_impl` | Table formatting |
//! | `tinyvec` | `tinyvec_impl` | Small-vector optimized types |
//! | `borsh` | `borsh_impl` | Binary serialization |
//!
//! # Module template
//!
//! Every integration module follows the same regional layout. Use this as
//! a template when adding a new optional integration:
//!
//! ```text
//! // region: Scalar conversions          (TryFromSexp + IntoR for T)
//! // region: Option conversions          (NA support — Option<T>)
//! // region: Vector conversions          (Vec<T>, Box<[T]>, slice views)
//! // region: Vec<Option<T>> conversions  (NA-aware vectors)
//! // region: R<X>Ops adapter trait       (e.g., RUuidOps, RUrlOps —
//! //                                      convenience methods callable
//! //                                      from #[miniextendr] code)
//! // region: Helper functions
//! // region: Unit tests
//! ```
//!
//! Exceptions: `rayon_bridge.rs` exposes a parallel-iteration API, not a
//! type-conversion adapter, and does not follow this shape. `serde_impl.rs`
//! is the JSON adapter (the *native* serde path lives in `crate::serde`).
//! Array-heavy upstreams (`ndarray_impl`, `arrow_impl`, `nalgebra_impl`,
//! `jiff_impl`) are larger because their type matrices are larger; the
//! per-region shape still applies.

// region: Rayon - Parallel computation

/// Rayon integration for parallel computation with R interop.
///
/// Provides:
/// - [`with_r_vec`][rayon_bridge::with_r_vec] - Chunk-based parallel fill into R vectors
/// - [`with_r_vec_map`][rayon_bridge::with_r_vec_map] - Element-wise parallel fill
/// - [`par_map`][rayon_bridge::par_map] - Transform input slice → R vector
/// - [`par_map2`][rayon_bridge::par_map2] - Two-input parallel map → R vector
/// - [`par_map3`][rayon_bridge::par_map3] - Three-input parallel map → R vector
/// - [`with_r_matrix`][rayon_bridge::with_r_matrix] - Column-wise parallel matrix fill
/// - [`with_r_array`][rayon_bridge::with_r_array] - Slab-wise parallel array fill
/// - [`reduce`][rayon_bridge::reduce] - Parallel reductions returning R scalars
/// - [`RParallelIterator`][rayon_bridge::RParallelIterator] - Adapter trait for R
///
/// Enable with `features = ["rayon"]`.
#[cfg(feature = "rayon")]
pub mod rayon_bridge;
#[cfg(feature = "rayon")]
pub use rayon_bridge::{RParallelExtend, RParallelIterator};
// endregion

// region: Parallel - thread pool control

/// Thread pool sizing, CRAN compliance (`_R_CHECK_LIMIT_CORES_`), and
/// cgroup-aware defaults for the rayon bridge. See `docs/RAYON.md`
/// ("Controlling parallelism from R").
///
/// Enable with `features = ["rayon"]`.
#[cfg(feature = "rayon")]
pub mod parallel;
// endregion

// region: Rand - Random number generation

/// Integration with the `rand` crate for R's RNG.
///
/// Provides:
/// - [`RRng`][rand_impl::RRng] - Wraps R's RNG, implements `rand::Rng`
/// - [`RDistributions`][rand_impl::RDistributions] - Direct access to R's native distributions
/// - [`RRngOps`][rand_impl::RRngOps] - Adapter trait for exposing custom RNGs to R
///
/// Enable with `features = ["rand"]`.
#[cfg(feature = "rand")]
pub mod rand_impl;
#[cfg(feature = "rand")]
pub use rand_impl::{RDistributionOps, RDistributions, RRng, RRngOps};

/// Re-export of `rand` so downstream crates can name its traits
/// (`RngExt`, `SeedableRng`, …) at the exact version [`RRng`] implements —
/// a mismatched direct `rand` dependency would fail trait coherence.
/// Enable with `features = ["rand"]`.
#[cfg(feature = "rand")]
pub use rand;

/// Re-export of `rand_distr` for probability distributions.
///
/// Provides distributions like `Normal`, `Exp`, `Uniform`, etc. that work
/// with [`RRng`]. Enable with `features = ["rand_distr"]`.
#[cfg(feature = "rand_distr")]
pub use rand_distr;
// endregion

// region: Either - Sum type

/// Integration with the `either` crate.
///
/// Provides [`TryFromSexp`](crate::TryFromSexp) and [`IntoR`](crate::IntoR) for [`Either<L, R>`][either::Either].
///
/// Enable with `features = ["either"]`.
#[cfg(feature = "either")]
pub mod either_impl;
#[cfg(feature = "either")]
pub use either_impl::{Either, Left, Right};
// endregion

// region: Ndarray - N-dimensional arrays

/// Integration with the `ndarray` crate.
///
/// Provides conversions between R vectors/matrices and ndarray types
/// (`Array1`, `Array2`, `ArrayView1`, `ArrayView2`).
///
/// Enable with `features = ["ndarray"]`.
#[cfg(feature = "ndarray")]
pub mod ndarray_impl;
#[cfg(feature = "ndarray")]
pub use ndarray_impl::{
    // Shared ownership
    ArcArray1,
    ArcArray2,
    // Owned arrays
    Array0,
    Array1,
    Array2,
    Array3,
    Array4,
    Array5,
    Array6,
    ArrayD,
    // Read-only views
    ArrayView0,
    ArrayView1,
    ArrayView2,
    ArrayView3,
    ArrayView4,
    ArrayView5,
    ArrayView6,
    ArrayViewD,
    // Mutable views
    ArrayViewMut0,
    ArrayViewMut1,
    ArrayViewMut2,
    ArrayViewMut3,
    ArrayViewMut4,
    ArrayViewMut5,
    ArrayViewMut6,
    ArrayViewMutD,
    // Index types
    Ix0,
    Ix1,
    Ix2,
    Ix3,
    Ix4,
    Ix5,
    Ix6,
    IxDyn,
    // Adapter traits
    RNdArrayOps,
    RNdIndex,
    RNdSlice,
    RNdSlice2D,
    // Shape builder
    ShapeBuilder,
};
#[cfg(feature = "ndarray")]
pub use ndarray_impl::{RndMat, RndVec};
// endregion

// region: Nalgebra - Linear algebra

/// Integration with the `nalgebra` crate.
///
/// Provides conversions between R vectors/matrices and nalgebra types
/// (`DVector`, `DMatrix`, `SVector`, `SMatrix`).
///
/// Enable with `features = ["nalgebra"]`.
#[cfg(feature = "nalgebra")]
pub mod nalgebra_impl;
#[cfg(feature = "nalgebra")]
pub use nalgebra_impl::{
    DMatrix, DVector, RDMatrix, RDVector, RMatrixOps, RVecStorage, RVectorOps, SMatrix, SVector,
};
// endregion

// region: Numeric types

/// Integration with the `num-bigint` crate.
///
/// Provides conversions for `BigInt` and `BigUint` via R character vectors.
///
/// Enable with `features = ["num-bigint"]`.
#[cfg(feature = "num-bigint")]
pub mod num_bigint_impl;
#[cfg(feature = "num-bigint")]
pub use num_bigint_impl::{
    BigInt, BigUint, RBigIntBitOps, RBigIntOps, RBigUintBitOps, RBigUintOps,
};

/// Integration with the `rust_decimal` crate.
///
/// Provides conversions for `Decimal` via R character vectors.
///
/// Enable with `features = ["rust_decimal"]`.
#[cfg(feature = "rust_decimal")]
pub mod rust_decimal_impl;
#[cfg(feature = "rust_decimal")]
pub use rust_decimal_impl::{Decimal, RDecimalOps};

/// Integration with the `ordered-float` crate.
///
/// Provides conversions for `OrderedFloat<f64>` and `OrderedFloat<f32>`.
///
/// Enable with `features = ["ordered-float"]`.
#[cfg(feature = "ordered-float")]
pub mod ordered_float_impl;
#[cfg(feature = "ordered-float")]
pub use ordered_float_impl::{OrderedFloat, ROrderedFloatOps};

/// Integration with the `num-complex` crate for complex number operations.
///
/// Provides conversions between R complex vectors (`CPLXSXP`) and `Complex<f64>`.
///
/// Enable with `features = ["num-complex"]`.
#[cfg(feature = "num-complex")]
pub mod num_complex_impl;
#[cfg(feature = "num-complex")]
pub use num_complex_impl::{Complex, RComplexOps};

/// Integration with the `num-traits` crate for generic numeric operations.
///
/// Provides adapter traits for generic numeric types:
/// - [`RNum`][num_traits_impl::RNum] - Basic numeric operations
/// - [`RSigned`][num_traits_impl::RSigned] - Signed number operations
/// - [`RFloat`][num_traits_impl::RFloat] - Floating-point operations
///
/// Enable with `features = ["num-traits"]`.
#[cfg(feature = "num-traits")]
pub mod num_traits_impl;
#[cfg(feature = "num-traits")]
pub use num_traits_impl::{RFloat, RNum, RSigned};
// endregion

// region: String/Text types

/// UUID support via the `uuid` crate.
///
/// Provides conversions between R character vectors and `Uuid` types.
///
/// Enable with `features = ["uuid"]`.
#[cfg(feature = "uuid")]
pub mod uuid_impl;
#[cfg(feature = "uuid")]
pub use uuid_impl::{RUuidOps, Uuid, uuid_helpers};

/// Regex support via the `regex` crate.
///
/// Provides compiled regular expressions from R character patterns.
///
/// Enable with `features = ["regex"]`.
#[cfg(feature = "regex")]
pub mod regex_impl;
#[cfg(feature = "regex")]
pub use regex_impl::{CaptureGroups, RCaptureGroups, RRegexOps, Regex};

/// Integration with the `url` crate for URL parsing and validation.
///
/// Provides conversions between R character vectors and `Url` types.
///
/// Enable with `features = ["url"]`.
#[cfg(feature = "url")]
pub mod url_impl;
#[cfg(feature = "url")]
pub use url_impl::{RUrlOps, Url, url_helpers};

/// Integration with the `aho-corasick` crate for multi-pattern string search.
///
/// Provides fast multi-pattern search using the Aho-Corasick algorithm.
///
/// Enable with `features = ["aho-corasick"]`.
#[cfg(feature = "aho-corasick")]
pub mod aho_corasick_impl;
#[cfg(feature = "aho-corasick")]
pub use aho_corasick_impl::{
    AhoCorasick, RAhoCorasickOps, aho_compile, aho_count_matches, aho_find_all, aho_find_all_flat,
    aho_find_first, aho_is_match, aho_replace_all,
};

/// Integration with the `globset` crate for shell-style glob matching.
///
/// Provides multi-pattern glob matching with path-aware defaults.
///
/// Enable with `features = ["globset"]`.
#[cfg(feature = "globset")]
pub mod globset_impl;
#[cfg(feature = "globset")]
pub use globset_impl::{
    Glob, GlobBuilder, GlobOptions, GlobSet, GlobSetBuilder, build_globset, globset_is_match,
    globset_matches,
};
// endregion

// region: Collections

/// IndexMap support via the `indexmap` crate.
///
/// Provides conversions between R named lists and `IndexMap<String, T>`.
///
/// Enable with `features = ["indexmap"]`.
#[cfg(feature = "indexmap")]
pub mod indexmap_impl;
#[cfg(feature = "indexmap")]
pub use indexmap_impl::{IndexMap, RIndexMapOps};
// endregion

// region: Date/Time

// Shared macro for the REALSXP-backed datetime conversion matrix (8 impls per type).
// Used by time_impl and jiff_impl; not a public export.
#[cfg(any(feature = "time", feature = "jiff"))]
mod datetime_realsxp;

/// Time and date support via the `time` crate.
///
/// Provides conversions between R date/time types and `time` crate types.
///
/// Enable with `features = ["time"]`.
#[cfg(feature = "time")]
pub mod time_impl;
#[cfg(feature = "time")]
pub use time_impl::{Date, Duration, OffsetDateTime, RDateTimeFormat, RDuration};

/// Date and time conversions via the `jiff` crate — first-class IANA timezone support.
///
/// Coexists with the `time` feature. Enable with `features = ["jiff"]`.
#[cfg(feature = "jiff")]
pub mod jiff_impl;
#[cfg(feature = "jiff")]
pub use jiff_impl::{
    Date as JiffDate, DateTime as JiffDateTime, JiffTimestampVec, JiffZonedVec, RDate, RDateTime,
    RSignedDuration, RSpan, RTime, RTimestamp, RZoned, SignedDuration, Span, Time as JiffTime,
    Timestamp, Zoned,
};
// endregion

// region: Serialization

/// Integration with `serde_json` for JSON string serialization.
///
/// Provides adapter traits for serializing/deserializing Rust types to/from JSON strings.
///
/// Enable with `features = ["serde_json"]`.
#[cfg(feature = "serde_json")]
pub mod serde_impl;
#[cfg(feature = "serde_json")]
pub use serde_impl::{
    FactorHandling, JsonOptions, JsonValue, NaHandling, RDeserialize, RJsonBridge, RJsonValueOps,
    RSerialize, SpecialFloatHandling, json_from_sexp, json_from_sexp_permissive,
    json_from_sexp_strict, json_from_sexp_with, json_into_sexp,
};

/// Integration with the `borsh` crate for binary serialization.
///
/// Provides [`Borsh<T>`][borsh_impl::Borsh] wrapper for borsh to/from raw vector conversions.
///
/// Enable with `features = ["borsh"]`.
#[cfg(feature = "borsh")]
pub mod borsh_impl;
#[cfg(feature = "borsh")]
pub use borsh_impl::{Borsh, RBorshOps, borsh_from_raw, borsh_to_raw};

/// Integration with the `toml` crate for TOML value conversions.
///
/// Provides conversions between TOML values and R types.
///
/// Enable with `features = ["toml"]`.
#[cfg(feature = "toml")]
pub mod toml_impl;
#[cfg(feature = "toml")]
pub use toml_impl::{RTomlOps, TomlValue, toml_from_str, toml_to_string, toml_to_string_pretty};
// endregion

// region: Byte/Binary handling

/// Integration with the `bytes` crate for byte buffer operations.
///
/// Provides adapter traits for byte buffer types.
///
/// Enable with `features = ["bytes"]`.
#[cfg(feature = "bytes")]
pub mod bytes_impl;
#[cfg(feature = "bytes")]
pub use bytes_impl::{Buf, BufMut, Bytes, BytesMut, RBuf, RBufMut};

/// Integration with the `sha2` crate for cryptographic hashing.
///
/// Provides SHA-256 and SHA-512 hashing helpers.
///
/// Enable with `features = ["sha2"]`.
#[cfg(feature = "sha2")]
pub mod sha2_impl;
#[cfg(feature = "sha2")]
pub use sha2_impl::{sha256_bytes, sha256_str, sha512_bytes, sha512_str};

/// Integration with the `blake3` crate for fast cryptographic hashing.
///
/// Provides BLAKE3 hashing helpers (hex + raw 32-byte digest).
///
/// Enable with `features = ["blake3"]`.
#[cfg(feature = "blake3")]
pub mod blake3_impl;
#[cfg(feature = "blake3")]
pub use blake3_impl::{blake3_bytes, blake3_hex, blake3_str};

/// Integration with the `md5` crate for legacy hashing.
///
/// MD5 is cryptographically broken — exposed for interop/checksums only.
///
/// Enable with `features = ["md5"]`.
#[cfg(feature = "md5")]
pub mod md5_impl;
#[cfg(feature = "md5")]
pub use md5_impl::{md5_bytes, md5_hex, md5_str};

/// Integration with the `zstd` crate for whole-buffer compression.
///
/// Provides `zstd_compress` / `zstd_decompress` (R raw in / raw out).
///
/// Enable with `features = ["zstd"]`.
#[cfg(feature = "zstd")]
pub mod zstd_impl;
#[cfg(feature = "zstd")]
pub use zstd_impl::{zstd_compress, zstd_decompress};
// endregion

// region: Bit manipulation

/// Integration with the `bitflags` crate.
///
/// Provides [`RFlags<T>`][bitflags_impl::RFlags] wrapper for bitflags ↔ integer conversions.
///
/// Enable with `features = ["bitflags"]`.
#[cfg(feature = "bitflags")]
pub mod bitflags_impl;
#[cfg(feature = "bitflags")]
pub use bitflags_impl::{Flags, RFlags};

/// Integration with the `bitvec` crate.
///
/// Provides conversions between R logical vectors and `BitVec` types.
///
/// Enable with `features = ["bitvec"]`.
#[cfg(feature = "bitvec")]
pub mod bitvec_impl;
#[cfg(feature = "bitvec")]
pub use bitvec_impl::{BitVec, Lsb0, Msb0, RBitVec};
// endregion

// region: Formatting

/// Integration with the `tabled` crate for table formatting.
///
/// Provides helpers for formatting data as ASCII/Unicode tables.
///
/// Enable with `features = ["tabled"]`.
#[cfg(feature = "tabled")]
pub mod tabled_impl;
#[cfg(feature = "tabled")]
pub use tabled_impl::{
    Builder, Table, Tabled, builder_to_string, table_from_vecs, table_to_string,
    table_to_string_opts, table_to_string_styled,
};
// endregion

// region: TinyVec - Small vector optimization

/// Integration with the `tinyvec` crate for small-vector optimization.
///
/// Provides conversions for `TinyVec<[T; N]>` and `ArrayVec<[T; N]>`:
/// - `TinyVec`: Growable, stores inline up to N elements, then spills to heap
/// - `ArrayVec`: Fixed capacity N, never allocates, errors if exceeded
///
/// Enable with `features = ["tinyvec"]`.
#[cfg(feature = "tinyvec")]
pub mod tinyvec_impl;
#[cfg(feature = "tinyvec")]
pub use tinyvec_impl::{Array, ArrayVec, TinyVec};
// endregion

// region: Arrow - Apache Arrow columnar format

/// Integration with the Apache Arrow columnar format.
///
/// Provides zero-copy (where possible) conversions between R vectors/data.frames
/// and Arrow arrays/RecordBatch.
///
/// Enable with `features = ["arrow"]`.
#[cfg(feature = "arrow")]
pub mod arrow_impl;
#[cfg(feature = "arrow")]
pub use arrow_impl::{
    Array as ArrowArray, ArrayRef, BooleanArray, DataType, Date32Array, DictionaryArray, Field,
    Float64Array, Int32Array, RecordBatch, Schema, StringArray, StringDictionaryArray,
    TimestampSecondArray, UInt8Array,
};
// endregion

// region: DataFusion - SQL query engine

/// Integration with Apache DataFusion query engine.
///
/// Provides `RSessionContext` for running SQL queries on R data frames.
/// Uses Tokio internally (block_on) so `#[miniextendr]` functions stay sync.
///
/// Enable with `features = ["datafusion"]` (implies `arrow`).
#[cfg(feature = "datafusion")]
pub mod datafusion_impl;
#[cfg(feature = "datafusion")]
pub use datafusion_impl::{RDataFrame, RSessionContext};
// endregion

// region: Log - Rust logging to R console

/// Integration with the `log` crate for routing Rust diagnostics to R's console.
///
/// Enable with `features = ["log"]`.
#[cfg(feature = "log")]
pub mod log_impl;
// endregion