miniextendr_api/

lib.rs

//! miniextendr-api: core runtime for Rust <-> R interop.
//!
//! This crate provides the FFI surface, safety wrappers, and macro re-exports
//! used by most miniextendr users. It is the primary dependency for building
//! Rust-powered R packages and exposing Rust types to R.
//!
//! At a glance:
//! - FFI bindings + checked wrappers for R's C API (`ffi`, `r_ffi_checked`).
//! - Conversions between Rust and R types (`IntoR`, `TryFromSexp`, `Coerce`).
//! - ALTREP traits, registration helpers, and iterator-backed ALTREP data types.
//! - Wrapper generation from Rust signatures (`#[miniextendr]`, automatic registration via linkme).
//! - Worker-thread pattern for panic isolation and `Drop` safety (`worker`).
//! - Class system support (S3, S4, S7, R6, env-style impl blocks).
//! - Cross-package trait ABI for type-erased dispatch (`trait_abi`).
//!
//! Most users should depend on this crate directly. For embedding R in
//! standalone binaries or integration tests, see `miniextendr-engine`.
//!
//! ## Quick start
//!
//! ```ignore
//! use miniextendr_api::miniextendr;
//!
//! #[miniextendr]
//! fn add(a: i32, b: i32) -> i32 {
//!     a + b
//! }
//! ```
//!
//! That's it — `#[miniextendr]` handles everything. Items self-register
//! at link time; `miniextendr_init!` generates the `R_init_*` function
//! that calls `package_init()` to register all routines with R.
//! Wrapper R code is produced from Rust doc comments (roxygen tags are
//! extracted) by the cdylib-based wrapper generator and committed into
//! `R/miniextendr_wrappers.R` so CRAN builds do not require codegen.
//!
//! ## GC protection and ownership
//!
//! R's garbage collector can reclaim any SEXP that isn't protected. miniextendr
//! provides three complementary protection mechanisms:
//!
//! | Strategy | Module | Lifetime | Release Order | Use Case |
//! |----------|--------|----------|---------------|----------|
//! | **PROTECT stack** | [`gc_protect`] | Within `.Call` | LIFO (stack) | Temporary allocations |
//! | **Preserve list** | [`preserve`] | Across `.Call`s | Any order | Long-lived R objects |
//! | **R ownership** | [`ExternalPtr`](struct@ExternalPtr) | Until R GCs | R decides | Rust data owned by R |
//!
//! Quick guide:
//!
//! **Temporary allocations during computation** -> [`ProtectScope`]
//! ```ignore
//! unsafe fn compute(x: SEXP) -> SEXP {
//!     let scope = ProtectScope::new();
//!     let temp = scope.protect(Rf_allocVector(REALSXP, 100));
//!     // ... work with temp ...
//!     result.into_raw()
//! } // UNPROTECT(n) called automatically
//! ```
//!
//! **R objects surviving across `.Call`s** -> [`preserve`]
//! ```ignore
//! // In RAllocator or similar long-lived context
//! let cell = unsafe { preserve::insert(backing_vec) };
//! // ... use across multiple .Calls ...
//! unsafe { preserve::release(cell) };
//! ```
//!
//! **Rust data owned by R** -> [`ExternalPtr`](struct@ExternalPtr)
//! ```ignore
//! #[miniextendr]
//! fn create_model() -> ExternalPtr<MyModel> {
//!     ExternalPtr::new(MyModel::new())
//! } // R owns it; Drop runs when R GCs
//! ```
//!
//! Note: ALTREP trait methods receive raw SEXP pointers from R's runtime.
//! These are safe to dereference because R guarantees valid SEXPs in ALTREP callbacks.
//!
//! ## Threading and safety
//!
//! R uses `longjmp` for errors, which can bypass Rust destructors. The default
//! pattern is to run Rust logic on a worker thread and marshal R API calls back
//! to the main R thread via `with_r_thread`. Most FFI wrappers are
//! main-thread routed via `#[r_ffi_checked]`. Use unchecked variants only when
//! you have arranged a safe context.
//!
//! With the `nonapi` feature, miniextendr can disable R's stack checking to allow
//! calls from other threads. R is still not thread-safe; serialize all R API use.
//!
//! ## Feature Flags
//!
//! ### Core Features
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `nonapi` | Non-API R symbols (stack controls, mutable `DATAPTR`). May break with R updates. |
//! | `rayon` | Parallel iterators via Rayon. Adds `RParallelIterator`, `RParallelExtend`. |
//! | `connections` | Experimental R connection framework. **Unstable R API.** |
//! | `indicatif` | Progress bars via R console. Requires `nonapi`. |
//! | `vctrs` | vctrs class construction (`new_vctr`, `new_rcrd`, `new_list_of`) and `#[derive(Vctrs)]`. |
//! | `worker-thread` | Worker thread for panic isolation and `Drop` safety. Without it, stubs run inline. |
//!
//! ### Type Conversions (Scalars & Vectors)
//!
//! | Feature | Rust Type | R Type | Notes |
//! |---------|-----------|--------|-------|
//! | `either` | `Either<L, R>` | Tries L then R | Union-like dispatch |
//! | `uuid` | `Uuid`, `Vec<Uuid>` | `character` | UUID ↔ string |
//! | `regex` | `Regex` | `character(1)` | Compiles pattern from R |
//! | `url` | `Url`, `Vec<Url>` | `character` | Validated URLs |
//! | `time` | `OffsetDateTime`, `Date` | `POSIXct`, `Date` | Date/time conversions |
//! | `ordered-float` | `OrderedFloat<f64>` | `numeric` | NaN-orderable floats |
//! | `num-bigint` | `BigInt`, `BigUint` | `character` | Arbitrary precision via strings |
//! | `rust_decimal` | `Decimal` | `character` | Fixed-point decimals |
//! | `num-complex` | `Complex<f64>` | `complex` | Native R complex support |
//! | `indexmap` | `IndexMap<String, T>` | named `list` | Preserves insertion order |
//! | `bitflags` | `RFlags<T>` | `integer` | Bitflags ↔ integer |
//! | `bitvec` | `RBitVec` | `logical` | Bit vectors ↔ logical |
//! | `tinyvec` | `TinyVec<[T; N]>`, `ArrayVec<[T; N]>` | vectors | Small-vector optimization |
//!
//! ### Matrix & Array Libraries
//!
//! | Feature | Types | Conversions |
//! |---------|-------|-------------|
//! | `ndarray` | `Array1`–`Array6`, `ArrayD`, views | R vectors/matrices ↔ ndarray |
//! | `nalgebra` | `DVector`, `DMatrix` | R vectors/matrices ↔ nalgebra |
//!
//! ### Serialization
//!
//! | Feature | Traits/Modules | Description |
//! |---------|----------------|-------------|
//! | `serde` | `RSerializeNative`, `RDeserializeNative` | Direct Rust ↔ R native serialization |
//! | `serde_json` | `RSerialize`, `RDeserialize` | JSON string serialization (includes `serde`) |
//! | `borsh` | `Borsh<T>` | Binary serialization ↔ raw vectors via Borsh |
//!
//! ### Adapter Traits (Generic Operations)
//!
//! | Feature | Traits | Use Case |
//! |---------|--------|----------|
//! | `num-traits` | `RNum`, `RSigned`, `RFloat` | Generic numeric operations |
//! | `bytes` | `RBuf`, `RBufMut` | Byte buffer operations |
//!
//! ### Text & Data Processing
//!
//! | Feature | Types/Functions | Description |
//! |---------|-----------------|-------------|
//! | `aho-corasick` | `AhoCorasick`, `aho_compile` | Fast multi-pattern string search |
//! | `toml` | `TomlValue`, `toml_from_str` | TOML parsing and serialization |
//! | `tabled` | `table_to_string` | ASCII/Unicode table formatting |
//! | `sha2` | `sha256_str`, `sha512_bytes` | Cryptographic hashing |
//!
//! ### Random Number Generation
//!
//! | Feature | Types | Description |
//! |---------|-------|-------------|
//! | `rand` | `RRng`, `RDistributions` | Wraps R's RNG with `rand` traits |
//! | `rand_distr` | Re-exports `rand_distr` | Additional distributions (Normal, Exp, etc.) |
//!
//! ### Binary Data
//!
//! | Feature | Types | Description |
//! |---------|-------|-------------|
//! | `raw_conversions` | `Raw<T>`, `RawSlice<T>` | POD types ↔ raw vectors via bytemuck |
//!
//! ### Project-wide Defaults (mutually exclusive where noted)
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `default-r6` | Default class system: R6 (mutually exclusive with `default-s7`) |
//! | `default-s7` | Default class system: S7 (mutually exclusive with `default-r6`) |
//! | `default-worker` | Default to worker thread dispatch (implies `worker-thread`) |
//! | `default-strict` | Default to strict mode for lossy integer conversions |
//! | `default-coerce` | Default to coerce mode for type conversions |
//!
//! ### Development / Diagnostics
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `doc-lint` | Warn on roxygen doc comment mismatches (enabled by default) |
//! | `macro-coverage` | Expose macro coverage test module for `cargo expand` auditing |
//! | `debug-preserve` | Enable `preserve::count()` diagnostic helpers (tests/benchmarks only) |
//! | `growth-debug` | Track and report collection growth events (zero-cost when off) |
//! | `refcount-fast-hash` | Use ahash for refcount arenas (enabled by default, not DOS-resistant) |
// Re-export linkme for use by generated code (distributed_slice entries)
#[doc(hidden)]
pub use linkme;

// Procedural macros (re-exported from miniextendr-macros)
#[doc(hidden)]
pub use miniextendr_macros::__mx_trait_impl_expand;
#[doc(inline)]
pub use miniextendr_macros::ExternalPtr;
#[doc(inline)]
pub use miniextendr_macros::RNativeType;
#[doc(inline)]
pub use miniextendr_macros::impl_typed_external;
#[doc(inline)]
pub use miniextendr_macros::list;
#[doc(inline)]
pub use miniextendr_macros::miniextendr;
#[doc(inline)]
pub use miniextendr_macros::miniextendr_init;
#[doc(inline)]
pub use miniextendr_macros::r_ffi_checked;
#[doc(inline)]
pub use miniextendr_macros::typed_list;
// Note: RFactor derive macro is re-exported - it shares the name with the RFactor trait
// but they're in different namespaces (derive macros vs types/traits)
#[cfg(feature = "vctrs")]
#[doc(inline)]
pub use miniextendr_macros::Vctrs;
// Note: MatchArg derive macro is re-exported - it shares the name with the MatchArg trait
// but they're in different namespaces (derive macros vs types/traits), same as RFactor.
#[doc(inline)]
pub use miniextendr_macros::{
    Altrep, AltrepComplex, AltrepInteger, AltrepList, AltrepLogical, AltrepRaw, AltrepReal,
    AltrepString, DataFrameRow, IntoList, MatchArg, PreferDataFrame, PreferExternalPtr, PreferList,
    PreferRNativeType, RFactor, TryFromList,
};

pub mod altrep;
pub mod altrep_bridge;
pub mod altrep_data;
pub mod altrep_ext;
pub mod altrep_impl;
pub mod altrep_sexp;
pub mod altrep_traits;

// Re-export for backward compatibility - RegisterAltrep was moved from altrep_registration to altrep
#[doc(hidden)]
pub mod altrep_registration {
    pub use crate::altrep::RegisterAltrep;
}
/// Raw R FFI bindings and low-level SEXP utilities.
///
/// Most users should prefer safe wrappers from higher-level modules.
pub mod ffi;

/// Automatic registration internals.
///
/// Items annotated with `#[miniextendr]` self-register at link time.
/// The C entrypoint calls [`registry::miniextendr_register_routines`] to
/// finalize registration with R. Users don't interact with this module.
pub mod registry;

/// Host-time generator of `wasm_registry.rs` — the WASM-side replacement for
/// linkme. See the module for full rationale.
///
/// Host-only — the writer reads the live linkme distributed slices to format
/// `wasm_registry.rs`, and linkme isn't available on wasm32 anyway.
#[cfg(not(target_arch = "wasm32"))]
pub mod wasm_registry_writer;

// Re-export high-level ALTREP data traits
pub use altrep_data::{
    AltComplexData,
    AltIntegerData,
    AltListData,
    AltLogicalData,
    AltRawData,
    AltRealData,
    AltStringData,
    AltrepDataptr,
    AltrepExtract,
    AltrepLen,
    // Iterator-backed ALTREP types (R-native)
    IterComplexData,
    // Iterator-backed ALTREP types (with Coerce support)
    IterIntCoerceData,
    IterIntData,
    IterIntFromBoolData,
    IterListData,
    IterLogicalData,
    IterRawData,
    IterRealCoerceData,
    IterRealData,
    IterState,
    IterStringData,
    Logical,
    Sortedness,
    // Sparse iterator-backed ALTREP types (compute-on-access)
    SparseIterComplexData,
    SparseIterIntData,
    SparseIterLogicalData,
    SparseIterRawData,
    SparseIterRealData,
    SparseIterState,
    // Streaming ALTREP types (chunk-cached reader closures)
    StreamingIntData,
    StreamingRealData,
    // Windowed iterator-backed ALTREP types
    WindowedIterIntData,
    WindowedIterRealData,
    WindowedIterState,
};
// Re-export RBase enum, AltrepGuard, and AltrepSexp
pub use altrep::RBase;
pub use altrep_sexp::{AltrepSexp, ensure_materialized};
pub use altrep_traits::AltrepGuard;

// ALTREP package name global - set by C entrypoint before ALTREP registration
// This is a pointer to a null-terminated C string provided by C code.
// Default: c"unknown" for safety if not set.
use std::sync::atomic::{AtomicPtr, Ordering};
static ALTREP_PKG_NAME_PTR: AtomicPtr<std::ffi::c_char> =
    AtomicPtr::new(c"unknown".as_ptr().cast_mut());

/// Returns the current ALTREP package name as a C string pointer.
/// This is set by the C entrypoint before ALTREP registration.
#[doc(hidden)]
pub struct AltrepPkgName;

impl AltrepPkgName {
    /// Get the package name pointer.
    #[inline]
    pub fn as_ptr() -> *const std::ffi::c_char {
        ALTREP_PKG_NAME_PTR.load(Ordering::Acquire)
    }
}

/// Opaque handle for ALTREP package name.
/// Use `ALTREP_PKG_NAME.as_ptr()` to get the C string pointer.
#[doc(hidden)]
pub static ALTREP_PKG_NAME: AltrepPkgName = AltrepPkgName;

/// Set the ALTREP package name. Called from C entrypoint.
/// # Safety
/// The provided pointer must point to a valid null-terminated C string
/// that lives for the duration of the R session.
///
/// The strict requirement is narrower: R copies the bytes via `install()`
/// inside each `R_make_alt*_class` call that consults this global (see
/// `RegisterClass` in R's `src/main/altrep.c`), so the pointer only has to
/// remain valid across those calls. We keep the session-lifetime contract
/// because we don't track which registrations are still pending; a string
/// literal passed from C satisfies both.
#[doc(hidden)]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_set_altrep_pkg_name(name: *const std::ffi::c_char) {
    let name = if name.is_null() {
        c"unknown".as_ptr()
    } else {
        name
    };
    ALTREP_PKG_NAME_PTR.store(name.cast_mut(), Ordering::Release);
}

// DllInfo global — stored during package_init, used by ALTREP class registration.
// R needs DllInfo to associate ALTREP classes with their package for serialization.
// Without it, readRDS in a fresh session can't find the class.
static ALTREP_DLL_INFO: AtomicPtr<std::ffi::c_void> = AtomicPtr::new(std::ptr::null_mut());

/// Get the stored DllInfo pointer for ALTREP class registration.
#[doc(hidden)]
pub fn altrep_dll_info() -> *mut ffi::DllInfo {
    ALTREP_DLL_INFO.load(Ordering::Acquire).cast()
}

/// Store the DllInfo pointer during package init.
#[doc(hidden)]
pub fn set_altrep_dll_info(dll: *mut ffi::DllInfo) {
    ALTREP_DLL_INFO.store(dll.cast(), Ordering::Release);
}

// Note: SexpExt is pub(crate), imported directly in modules that need it
pub mod from_r;
pub mod into_r;
pub mod into_r_error;
pub use into_r::{Altrep, IntoR, IntoRAltrep};
pub use into_r_error::IntoRError;
pub mod into_r_as;
pub use into_r_as::{IntoRAs, StorageCoerceError};
pub mod pump;
pub mod unwind_protect;
pub mod worker;

// Re-export commonly used worker items at root for convenience
pub use worker::{Sendable, is_r_main_thread, with_r_thread};

// Required exports for generated code and initialization
pub use worker::miniextendr_runtime_init;

// Thread safety utilities for calling R from non-main threads
pub mod thread;

// Collection growth debug instrumentation (diagnostics)
#[cfg(feature = "growth-debug")]
pub mod growth_debug;

/// Track a collection growth (reallocation) event.
///
/// When the `growth-debug` feature is enabled, increments a thread-local counter
/// for the named collection. When disabled, compiles to a no-op.
///
/// # Example
///
/// ```ignore
/// let old_cap = vec.capacity();
/// vec.push(item);
/// if vec.capacity() != old_cap {
///     track_growth!("my_vec");
/// }
/// ```
#[cfg(feature = "growth-debug")]
#[macro_export]
macro_rules! track_growth {
    ($name:expr) => {
        $crate::growth_debug::record_growth($name)
    };
}

/// Track a collection growth (reallocation) event.
///
/// No-op when `growth-debug` feature is disabled.
#[cfg(not(feature = "growth-debug"))]
#[macro_export]
macro_rules! track_growth {
    ($name:expr) => {};
}

/// Print and reset all growth counters.
///
/// When the `growth-debug` feature is enabled, prints all tracked growth events
/// to stderr and resets the counters. When disabled, compiles to a no-op.
#[cfg(feature = "growth-debug")]
#[macro_export]
macro_rules! report_growth {
    () => {
        $crate::growth_debug::report_and_reset()
    };
}

/// Print and reset all growth counters.
///
/// No-op when `growth-debug` feature is disabled.
#[cfg(not(feature = "growth-debug"))]
#[macro_export]
macro_rules! report_growth {
    () => {};
}

// `indicatif` progress integration (R console)
#[cfg(feature = "indicatif")]
pub mod progress;
#[cfg(feature = "indicatif")]
pub use indicatif;

// Stack size constants and builder (always available)
#[cfg(windows)]
pub use thread::WINDOWS_R_STACK_SIZE;
pub use thread::{DEFAULT_R_STACK_SIZE, RThreadBuilder};

// Stack checking control (requires nonapi feature)
#[cfg(feature = "nonapi")]
pub use thread::{StackCheckGuard, scope_with_r, spawn_with_r, with_stack_checking_disabled};

// Panic telemetry hook for structured panic→R-error diagnostics
pub mod panic_telemetry;

// Unified FFI guard for catching panics at Rust-R boundaries
pub mod ffi_guard;
pub use ffi_guard::{GuardMode, guarded_ffi_call, guarded_ffi_call_with_fallback};

// Runtime wrapper for R data.frame objects
pub mod dataframe;
pub use dataframe::{DataFrameError, DataFrameView};

// Strict conversion helpers for #[miniextendr(strict)]
pub mod strict;

// Cached R class attribute SEXPs (POSIXct, Date, data.frame, etc.)
pub mod cached_class;

// Error value transport for #[miniextendr(error_in_r)]
pub mod error_value;

// Error handling helpers (r_warning, r_print!, r_println! macros)
pub mod error;
pub use error::r_warning;

// RNG (random number generation) utilities
pub mod rng;
pub use rng::{RngGuard, with_rng};

// Re-export from_r
pub use from_r::{SexpError, SexpLengthError, SexpNaError, SexpTypeError, TryFromSexp};

// Encoding / locale probing (mainly for debugging). The module is always
// compiled; the symbols that reference non-exported state from R's `Defn.h`
// (`known_to_be_utf8`, `utf8locale`, ...) are gated inside the module behind
// `#[cfg(feature = "nonapi")]` so a default build never links them.
pub mod encoding;

// Expression evaluation helpers (RSymbol, RCall, REnv)
pub mod expression;
pub use expression::{RCall, REnv, RSymbol};

// S4 slot access and class checking helpers
pub mod s4_helpers;

// Note: RNativeType is pub(crate), imported directly in modules that need it

pub mod backtrace;

pub mod coerce;
pub use coerce::{Coerce, CoerceError, Coerced, TryCoerce};

/// Traits for R's `as.<class>()` coercion functions.
///
/// This module provides traits for implementing R's generic coercion methods
/// (`as.data.frame()`, `as.list()`, `as.character()`, etc.) for Rust types
/// wrapped in [`ExternalPtr`](struct@ExternalPtr).
///
/// See the [`as_coerce`] module documentation for usage examples.
pub mod as_coerce;
pub use as_coerce::{
    // Core coercion traits
    AsCharacter,
    // Error type
    AsCoerceError,
    AsComplex,
    AsDataFrame,
    AsDate,
    AsEnvironment,
    AsFactor,
    AsFunction,
    AsInteger,
    AsList as AsListCoerce,
    AsLogical,
    AsMatrix,
    AsNumeric,
    AsPOSIXct,
    AsRaw,
    AsVector,
    // Helpers
    SUPPORTED_AS_GENERICS,
    is_supported_as_generic,
};

pub mod condition;
pub use condition::{AsRError, RCondition};
pub mod convert;
/// Support for R `...` arguments represented as a validated list.
pub mod dots;
pub mod list;
pub mod missing;
pub mod named_vector;
pub mod strvec;
pub mod typed_list;
pub use convert::{
    AsDisplay, AsDisplayVec, AsExternalPtr, AsExternalPtrExt, AsFromStr, AsFromStrVec, AsList,
    AsListExt, AsNamedList, AsNamedListExt, AsNamedVector, AsNamedVectorExt, AsRNative,
    AsRNativeExt, Collect, CollectNA, CollectNAInt, CollectStrings, DataFrame, IntoDataFrame,
    ToDataFrame, ToDataFrameExt,
};
#[cfg(feature = "serde")]
pub use convert::{AsSerializeRow, SerializeDataFrame};
pub use into_r::Lazy;
pub use list::{
    IntoList, List, ListAccumulator, ListBuilder, ListMut, NamedList, TryFromList, collect_list,
};
pub use missing::{Missing, is_missing_arg};
pub use named_vector::{AtomicElement, NamedVector};
pub use strvec::{
    ProtectedStrVec, ProtectedStrVecCowIter, ProtectedStrVecIter, StrVec, StrVecBuilder,
    StrVecCowIter, StrVecIter,
};
pub use typed_list::{
    TypeSpec, TypedEntry, TypedList, TypedListError, TypedListSpec, actual_type_string,
    sexptype_name, validate_list,
};

// External pointer module - Box-like owned pointer wrapping R's EXTPTRSXP
pub mod externalptr;

// Connection framework (unstable R API - use with caution)
#[cfg(feature = "connections")]
pub mod connection;
// txtProgressBar handle — drives utils::txtProgressBar from Rust
#[cfg(feature = "connections")]
pub mod txt_progress_bar;
pub use externalptr::{
    ErasedExternalPtr,
    ExternalPtr,
    ExternalSlice,
    IntoExternalPtr,
    TypedExternal,
    // ALTREP helpers (checked)
    altrep_data1_as,
    // ALTREP helpers (unchecked - for performance-critical callbacks)
    altrep_data1_as_unchecked,
    altrep_data1_mut,
    altrep_data1_mut_unchecked,
    altrep_data2_as,
    altrep_data2_as_unchecked,
};

// TypedExternal implementations for std types
pub mod externalptr_std;

// Deprecated: DLL preserve list. Use ProtectPool or R_PreserveObject instead.
// Kept for benchmark comparisons.
pub mod preserve;

// GC protection toolkit (PROTECT stack RAII wrappers)
pub mod gc_protect;
pub use gc_protect::{OwnedProtect, ProtectIndex, ProtectScope, Protector, ReprotectSlot, Root};

// VECSXP pool with generational keys (slotmap-backed)
pub mod protect_pool;
pub use protect_pool::{ProtectKey, ProtectPool};

// Reference-counted GC protection (BTreeMap + VECSXP backing)
pub mod refcount_protect;
pub use refcount_protect::{
    Arena, ArenaGuard, HashMapArena, MapStorage, RefCountedArena, RefCountedGuard,
    ThreadLocalArena, ThreadLocalArenaOps, ThreadLocalHashArena,
};

pub mod allocator;
pub use allocator::RAllocator;

pub mod r_memory;

// region: Trait ABI Support
//
// Cross-package trait dispatch using a stable C ABI.
// See `trait_abi` module docs for details.

/// ABI types for cross-package trait dispatch.
///
/// This module defines the stable, C-compatible types used for runtime trait
/// dispatch across R package boundaries.
pub mod abi;

/// C-callable mx_abi functions (mx_wrap, mx_get, mx_query, mx_abi_register).
///
/// These are registered via `R_RegisterCCallable` during package init and
/// loaded by consumer packages via `R_GetCCallable`.
pub mod mx_abi;

/// Package initialization (`miniextendr_init!` support).
///
/// Consolidates all init steps into [`init::package_init`].
pub mod init;

/// Runtime support for trait ABI operations.
///
/// Provides C-callable loading and type conversion helpers for trait ABI support.
pub mod trait_abi;

/// vctrs class construction and trait support.
///
/// Provides helpers for building vctrs-compatible R objects and traits
/// for describing vctrs class metadata from Rust types.
///
/// Enable with `features = ["vctrs"]`.
#[cfg(feature = "vctrs")]
pub mod vctrs;
#[cfg(feature = "vctrs")]
pub use vctrs::{
    IntoVctrs, VctrsBuildError, VctrsClass, VctrsKind, VctrsListOf, VctrsRecord, new_list_of,
    new_rcrd, new_vctr,
};

// Re-export key ABI types at crate root for convenience
pub use abi::{mx_base_vtable, mx_erased, mx_meth, mx_tag};
pub use trait_abi::TraitView;
// endregion

// region: Marker Traits
//
// Marker traits for types derived with proc-macros.
// These enable compile-time identification and blanket implementations.

/// Marker traits for proc-macro derived types.
pub mod markers;
pub use markers::{PrefersDataFrame, PrefersExternalPtr, PrefersList, PrefersRNativeType};
// endregion

// region: Adapter Traits
//
// Built-in adapter traits with blanket implementations for standard library traits.
// These allow any Rust type implementing Debug, Display, Hash, Ord, etc. to be
// exposed to R without boilerplate.

/// Built-in adapter traits for std library traits.
///
/// Provides [`RDebug`], [`RDisplay`], [`RHash`], [`ROrd`], [`RPartialOrd`],
/// [`RError`], [`RFromStr`], [`RClone`], [`RCopy`], [`RDefault`], [`RIterator`],
/// [`RExtend`], and [`RFromIter`] with blanket implementations where possible.
/// See module docs for usage.
///
/// [`RDebug`]: adapter_traits::RDebug
/// [`RDisplay`]: adapter_traits::RDisplay
/// [`RHash`]: adapter_traits::RHash
/// [`ROrd`]: adapter_traits::ROrd
/// [`RPartialOrd`]: adapter_traits::RPartialOrd
/// [`RError`]: adapter_traits::RError
/// [`RFromStr`]: adapter_traits::RFromStr
/// [`RClone`]: adapter_traits::RClone
/// [`RCopy`]: adapter_traits::RCopy
/// [`RDefault`]: adapter_traits::RDefault
/// [`RIterator`]: adapter_traits::RIterator
/// [`RExtend`]: adapter_traits::RExtend
/// [`RFromIter`]: adapter_traits::RFromIter
pub mod adapter_traits;
pub use adapter_traits::{
    RClone, RCopy, RDebug, RDefault, RDisplay, RError, RExtend, RFromIter, RFromStr, RHash,
    RIterator, RMakeIter, ROrd, RPartialOrd, RToVec,
};

/// This is used to ensure the macros of `miniextendr-macros` treat this crate as a "user crate"
/// atleast in the `macro_coverage`
#[doc(hidden)]
extern crate self as miniextendr_api;

#[cfg(feature = "macro-coverage")]
#[doc(hidden)]
pub mod macro_coverage;
// endregion

// region: Optional integrations with external crates (feature-gated)
//
// All optional feature integrations are organized in the `optionals` module.
// Types are re-exported at crate root for backwards compatibility.

/// 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.
/// See the [module documentation][optionals] for a complete list of available features.
pub mod optionals;

// Re-export optional types at crate root for backwards compatibility
#[cfg(feature = "rayon")]
pub use optionals::rayon_bridge;
#[cfg(feature = "rayon")]
pub use optionals::{RParallelExtend, RParallelIterator};

#[cfg(feature = "rand_distr")]
pub use optionals::rand_distr;
#[cfg(feature = "rand")]
pub use optionals::rand_impl;
#[cfg(feature = "rand")]
pub use optionals::{RDistributionOps, RDistributions, RRng, RRngOps};

#[cfg(feature = "either")]
pub use optionals::either_impl;
#[cfg(feature = "either")]
pub use optionals::{Either, Left, Right};

#[cfg(feature = "ndarray")]
pub use optionals::ndarray_impl;
#[cfg(feature = "ndarray")]
pub use optionals::{
    ArcArray1, ArcArray2, Array0, Array1, Array2, Array3, Array4, Array5, Array6, ArrayD,
    ArrayView0, ArrayView1, ArrayView2, ArrayView3, ArrayView4, ArrayView5, ArrayView6, ArrayViewD,
    ArrayViewMut0, ArrayViewMut1, ArrayViewMut2, ArrayViewMut3, ArrayViewMut4, ArrayViewMut5,
    ArrayViewMut6, ArrayViewMutD, Ix0, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn, RNdArrayOps, RNdIndex,
    RNdSlice, RNdSlice2D, ShapeBuilder,
};

#[cfg(feature = "nalgebra")]
pub use optionals::nalgebra_impl;
#[cfg(feature = "nalgebra")]
pub use optionals::{DMatrix, DVector, RMatrixOps, RVectorOps, SMatrix, SVector};

#[cfg(feature = "num-bigint")]
pub use optionals::num_bigint_impl;
#[cfg(feature = "num-bigint")]
pub use optionals::{BigInt, BigUint, RBigIntBitOps, RBigIntOps, RBigUintBitOps, RBigUintOps};

#[cfg(feature = "rust_decimal")]
pub use optionals::rust_decimal_impl;
#[cfg(feature = "rust_decimal")]
pub use optionals::{Decimal, RDecimalOps};

#[cfg(feature = "ordered-float")]
pub use optionals::ordered_float_impl;
#[cfg(feature = "ordered-float")]
pub use optionals::{OrderedFloat, ROrderedFloatOps};

#[cfg(feature = "num-complex")]
pub use optionals::num_complex_impl;
#[cfg(feature = "num-complex")]
pub use optionals::{Complex, RComplexOps};

#[cfg(feature = "num-traits")]
pub use optionals::num_traits_impl;
#[cfg(feature = "num-traits")]
pub use optionals::{RFloat, RNum, RSigned};

#[cfg(feature = "uuid")]
pub use optionals::uuid_impl;
#[cfg(feature = "uuid")]
pub use optionals::{RUuidOps, Uuid, uuid_helpers};

#[cfg(feature = "regex")]
pub use optionals::regex_impl;
#[cfg(feature = "regex")]
pub use optionals::{CaptureGroups, RCaptureGroups, RRegexOps, Regex};

#[cfg(feature = "url")]
pub use optionals::url_impl;
#[cfg(feature = "url")]
pub use optionals::{RUrlOps, Url, url_helpers};

#[cfg(feature = "aho-corasick")]
pub use optionals::aho_corasick_impl;
#[cfg(feature = "aho-corasick")]
pub use optionals::{
    AhoCorasick, RAhoCorasickOps, aho_compile, aho_count_matches, aho_find_all, aho_find_all_flat,
    aho_find_first, aho_is_match, aho_replace_all,
};

#[cfg(feature = "indexmap")]
pub use optionals::indexmap_impl;
#[cfg(feature = "indexmap")]
pub use optionals::{IndexMap, RIndexMapOps};

#[cfg(feature = "time")]
pub use optionals::time_impl;
#[cfg(feature = "time")]
pub use optionals::{Date, Duration, OffsetDateTime, RDateTimeFormat, RDuration};
#[cfg(feature = "time")]
pub use time;

#[cfg(feature = "jiff")]
pub use jiff;
#[cfg(feature = "jiff")]
pub use optionals::jiff_impl;
#[cfg(feature = "jiff")]
pub use optionals::{
    JiffDate, JiffDateTime, JiffTime, JiffTimestampVec, JiffZonedVec, RDate, RDateTime,
    RSignedDuration, RSpan, RTime, RTimestamp, RZoned, SignedDuration, Span, Timestamp, Zoned,
};

#[cfg(feature = "serde_json")]
pub use optionals::serde_impl;
#[cfg(feature = "toml")]
pub use optionals::toml_impl;
#[cfg(feature = "serde_json")]
pub use optionals::{
    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,
};
#[cfg(feature = "toml")]
pub use optionals::{RTomlOps, TomlValue, toml_from_str, toml_to_string, toml_to_string_pretty};

#[cfg(feature = "bytes")]
pub use optionals::bytes_impl;
#[cfg(feature = "bytes")]
pub use optionals::{Buf, BufMut, Bytes, BytesMut, RBuf, RBufMut};

#[cfg(feature = "sha2")]
pub use optionals::sha2_impl;
#[cfg(feature = "sha2")]
pub use optionals::{sha256_bytes, sha256_str, sha512_bytes, sha512_str};

#[cfg(feature = "borsh")]
pub use optionals::borsh_impl;
#[cfg(feature = "borsh")]
pub use optionals::{Borsh, RBorshOps, borsh_from_raw, borsh_to_raw};

#[cfg(feature = "bitflags")]
pub use bitflags;
#[cfg(feature = "bitflags")]
pub use optionals::bitflags_impl;
#[cfg(feature = "bitflags")]
pub use optionals::{Flags, RFlags};

#[cfg(feature = "bitvec")]
pub use optionals::bitvec_impl;
#[cfg(feature = "bitvec")]
pub use optionals::{BitVec, Lsb0, Msb0, RBitVec};

#[cfg(feature = "tabled")]
pub use optionals::tabled_impl;
#[cfg(feature = "tabled")]
pub use optionals::{
    Builder, Table, Tabled, builder_to_string, table_from_vecs, table_to_string,
    table_to_string_opts, table_to_string_styled,
};

#[cfg(feature = "tinyvec")]
pub use optionals::tinyvec_impl;
#[cfg(feature = "tinyvec")]
pub use optionals::{Array, ArrayVec, TinyVec};

#[cfg(feature = "arrow")]
pub use optionals::arrow_impl;
#[cfg(feature = "arrow")]
pub use optionals::{
    ArrayRef, ArrowArray, BooleanArray, DataType, Date32Array, DictionaryArray, Field,
    Float64Array, Int32Array, RecordBatch, Schema, StringArray, StringDictionaryArray,
    TimestampSecondArray, UInt8Array,
};

#[cfg(feature = "datafusion")]
pub use optionals::RSessionContext;
#[cfg(feature = "datafusion")]
pub use optionals::datafusion_impl;

/// N-dimensional R arrays with const generic dimension count.
pub mod rarray;
pub use rarray::{RArray, RArray3D, RMatrix, RVector};

/// Direct R serialization via serde (no JSON intermediate).
///
/// Provides efficient type-preserving conversions between Rust types and native R objects:
/// - [`AsSerialize<T>`][serde::AsSerialize] - Wrapper for returning `Serialize` types from `#[miniextendr]` functions
/// - [`RSerializeNative`][serde::RSerializeNative] - Convert Rust → R (struct → named list)
/// - [`RDeserializeNative`][serde::RDeserializeNative] - Convert R → Rust (named list → struct)
///
/// Enable with `features = ["serde"]`.
///
/// See the [`serde`] module documentation for type mappings and examples.
#[cfg(feature = "serde")]
pub mod serde;
/// Re-export the upstream `serde` crate (aliased to avoid conflict with [`mod serde`]).
///
/// Downstream crates can use `miniextendr_api::serde_crate::{Serialize, Deserialize}`
/// and `#[serde(crate = "miniextendr_api::serde_crate")]` to avoid a direct `serde` dep.
#[cfg(feature = "serde")]
pub use ::serde as serde_crate;

/// Integration with the `bytemuck` crate for POD type conversions.
///
/// Provides explicit, safe conversions between Rust POD (Plain Old Data) types
/// and R raw vectors:
/// - `Raw<T>` - Single POD value (headerless, native layout)
/// - `RawSlice<T>` - Sequence of POD values (headerless)
/// - `RawTagged<T>` / `RawSliceTagged<T>` - With header metadata
///
/// Enable with `features = ["raw_conversions"]`.
///
/// ```ignore
/// use bytemuck::{Pod, Zeroable};
/// use miniextendr_api::raw_conversions::{Raw, RawSlice};
///
/// #[derive(Copy, Clone, Pod, Zeroable)]
/// #[repr(C)]
/// struct Vec3 { x: f32, y: f32, z: f32 }
///
/// #[miniextendr]
/// fn encode(x: f64, y: f64, z: f64) -> Raw<Vec3> {
///     Raw(Vec3 { x: x as f32, y: y as f32, z: z as f32 })
/// }
/// ```
#[cfg(feature = "raw_conversions")]
pub mod raw_conversions;
#[cfg(feature = "raw_conversions")]
pub use raw_conversions::{
    Pod, Raw, RawError, RawHeader, RawSlice, RawSliceTagged, RawTagged, Zeroable, raw_from_bytes,
    raw_slice_from_bytes, raw_slice_to_bytes, raw_to_bytes,
};

/// `match.arg`-style string conversion for enums.
///
/// Provides the [`MatchArg`] trait for converting Rust enums to/from R character
/// strings with partial matching, like R's `match.arg()`.
/// Use `#[derive(MatchArg)]` on C-style enums to auto-generate the implementation.
pub mod match_arg;
pub use match_arg::{
    MatchArg, MatchArgError, choices_sexp, match_arg_from_sexp, match_arg_vec_from_sexp,
    match_arg_vec_into_sexp,
};

/// Factor support for enum ↔ R factor conversions.
///
/// Provides the [`RFactor`] trait for converting Rust enums to/from R factors.
/// Use `#[derive(RFactor)]` on C-style enums to auto-generate the implementation.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::RFactor;
///
/// #[derive(Copy, Clone, RFactor)]
/// enum Color { Red, Green, Blue }
///
/// #[miniextendr]
/// fn color_name(c: Color) -> &'static str {
///     match c {
///         Color::Red => "red",
///         Color::Green => "green",
///         Color::Blue => "blue",
///     }
/// }
/// ```
pub mod factor;
pub use factor::{
    Factor, FactorMut, FactorOptionVec, FactorVec, RFactor, UnitEnumFactor, build_factor,
    build_levels_sexp, build_levels_sexp_cached, factor_from_sexp,
};

/// Convenience re-exports for common miniextendr items.
///
/// A single `use miniextendr_api::prelude::*;` brings into scope the most
/// commonly used macros, traits, types, and helpers.
pub mod prelude;
// endregion