miniextendr_api/lib.rs
1//! miniextendr-api: core runtime for Rust <-> R interop.
2//!
3//! This crate provides the FFI surface, safety wrappers, and macro re-exports
4//! used by most miniextendr users. It is the primary dependency for building
5//! Rust-powered R packages and exposing Rust types to R.
6//!
7//! At a glance:
8//! - FFI bindings + checked wrappers for R's C API (`sys`, `r_ffi_checked`).
9//! - Conversions between Rust and R types (`IntoR`, `TryFromSexp`, `Coerce`).
10//! - ALTREP traits, registration helpers, and iterator-backed ALTREP data types.
11//! - Wrapper generation from Rust signatures (`#[miniextendr]`, automatic registration via linkme).
12//! - Main-thread unwind protection (`unwind_protect`) and the main-thread check (`thread`).
13//! - Class system support (S3, S4, S7, R6, env-style impl blocks).
14//! - Cross-package trait ABI for type-erased dispatch (`trait_abi`).
15//!
16//! Most users should depend on this crate directly. For embedding R in
17//! standalone binaries or integration tests, see `miniextendr-engine`.
18//!
19//! ## Quick start
20//!
21//! ```ignore
22//! use miniextendr_api::miniextendr;
23//!
24//! #[miniextendr]
25//! fn add(a: i32, b: i32) -> i32 {
26//! a + b
27//! }
28//! ```
29//!
30//! That's it — `#[miniextendr]` handles everything. Items self-register
31//! at link time; `miniextendr_init!` generates the `R_init_*` function
32//! that calls `package_init()` to register all routines with R.
33//! Wrapper R code is produced from Rust doc comments (roxygen tags are
34//! extracted) by loading the freshly linked package library and calling the
35//! registry writer. `R/miniextendr-wrappers.R` is regenerated during
36//! development installs, kept out of git, and shipped from disk in release
37//! tarballs; roxygen2 derives the tracked `NAMESPACE` and `man/*.Rd` files.
38//!
39//! ## Choosing the right API
40//!
41//! miniextendr has several places where two or more APIs reach the same
42//! goal with different tradeoffs — a stricter / safer / more validated
43//! option, and a looser / easier / less protective one. The most common
44//! pairs are:
45//!
46//! | I'm reaching for... | Consider also | Why |
47//! |---|---|---|
48//! | default `IntoR` for `i64` / `u64` / `isize` / `usize` (silently widens to `REALSXP` on overflow) | `#[miniextendr(strict)]` → [`crate::strict`] helpers (panic on overflow) | strict catches the truncation bugs caused by R having no native 64-bit integer type |
49//! | [`Coerce`] (infallible widening) | [`TryCoerce`] (fallible) | the source range can exceed the target type |
50//! | `Rf_*_unchecked` FFI | checked variants | unchecked is only safe inside ALTREP callbacks, `with_r_unwind_protect`, or `with_r_thread` — MXL301 lint enforces |
51//! | `panic!(msg)` | `miniextendr_api::error!("msg", class = "...")` | typed conditions let R-side `tryCatch` handlers route by class |
52//! | raw `_dots: &Dots` | `#[miniextendr(dots = typed_list!(...))]` | validation moves from runtime to macro call site |
53//! | `#[derive(AltrepInteger)]` field-based | `#[altrep(manual)]` + handwritten traits | when custom storage or computed-on-access can't fit the derive |
54//! | hand-rolled [`TryFromSexp`] + [`IntoR`] | `#[derive(RSerializeNative)]` (serde feature) | serde is ergonomic for nested structs; hand-rolled is zero-overhead and fully controlled |
55//!
56//! Project-wide defaults are controlled by mutually-exclusive cargo
57//! features — see the "Project-wide Defaults" feature table below.
58//!
59//! ### Default opinion
60//!
61//! When in doubt, pick the **stricter** path. The framework's default
62//! stance is "fail loudly, leave a trail." The looser variants exist for
63//! cases where the cost is measured or the looser semantics are correct
64//! for your data — they are not the default.
65//!
66//! ## GC protection and ownership
67//!
68//! R's garbage collector can reclaim any SEXP that isn't protected. miniextendr
69//! provides three complementary protection mechanisms:
70//!
71//! | Strategy | Module | Lifetime | Release Order | Use Case |
72//! |----------|--------|----------|---------------|----------|
73//! | **PROTECT stack** | [`gc_protect`] | Within `.Call` | LIFO (stack) | Temporary allocations |
74//! | **VECSXP pool** | [`protect_pool`] | Until released or the pool drops | Any order | Values a struct owns; many values; cross-call roots |
75//! | **R ownership** | [`ExternalPtr`](struct@ExternalPtr) | Until R GCs | R decides | Rust data owned by R |
76//!
77//! Quick guide:
78//!
79//! **Temporary allocations during computation** -> [`ProtectScope`]
80//! ```ignore
81//! unsafe fn compute(x: SEXP) -> SEXP {
82//! let scope = ProtectScope::new();
83//! let temp = scope.protect(Rf_allocVector(REALSXP, 100));
84//! // ... work with temp ...
85//! result.into_raw()
86//! } // UNPROTECT(n) called automatically
87//! ```
88//!
89//! **Values a struct owns, many values, or any drop order** -> [`ProtectPool`]
90//! ```ignore
91//! // The per-call root set: keep each value until the pool drops.
92//! let mut roots = ProtectPool::new(ProtectPool::DEFAULT_CAPACITY);
93//! let ids = roots.root(vec![1, 2, 3]);
94//!
95//! // Or release one value at a time, in any order, even across `.Call`s.
96//! let key = roots.insert(backing_vec);
97//! roots.release(key);
98//! ```
99//!
100//! **One long-lived object** -> [`Preserved`] (one `R_PreserveObject` root)
101//!
102//! **Rust data owned by R** -> [`ExternalPtr`](struct@ExternalPtr)
103//! ```ignore
104//! #[miniextendr]
105//! fn create_model() -> ExternalPtr<MyModel> {
106//! ExternalPtr::new(MyModel::new())
107//! } // R owns it; Drop runs when R GCs
108//! ```
109//!
110//! Note: ALTREP trait methods receive raw SEXP pointers from R's runtime.
111//! These are safe to dereference because R guarantees valid SEXPs in ALTREP callbacks.
112//!
113//! ## Threading and safety
114//!
115//! R uses `longjmp` for errors, which can bypass Rust destructors. Generated
116//! wrappers run inline on R's main thread inside `R_UnwindProtect`. Most FFI
117//! wrappers check for R's main thread via `#[r_ffi_checked]` (through
118//! [`with_r_thread`]). Use unchecked variants only when you have arranged a
119//! safe context.
120//!
121//! The `nonapi` feature exposes legacy controls for R's process-global stack
122//! bounds. Disabling that check does **not** make R's API safe off the main
123//! thread; package code must keep R API work on the recorded main thread.
124//!
125//! ## Feature Flags
126//!
127//! ### Core Features
128//!
129//! | Feature | Description |
130//! |---------|-------------|
131//! | `nonapi` | Non-API R symbols (stack controls, mutable `DATAPTR`). May break with R updates. |
132//! | `rayon` | Parallel iterators via Rayon. Adds `RParallelIterator`, `RParallelExtend`. |
133//! | `connections` | Experimental R connection framework. **Unstable R API.** |
134//! | `indicatif` | Progress bars routed through R connections. Requires `nonapi` + `connections`. |
135//! | `vctrs` | vctrs class construction (`new_vctr`, `new_rcrd`, `new_list_of`) and `#[derive(Vctrs)]`. |
136//!
137//! ### Type Conversions (Scalars & Vectors)
138//!
139//! | Feature | Rust Type | R Type | Notes |
140//! |---------|-----------|--------|-------|
141//! | `either` | `Either<L, R>` | Tries L then R | Union-like dispatch |
142//! | `uuid` | `Uuid`, `Vec<Uuid>` | `character` | UUID ↔ string |
143//! | `regex` | `Regex` | `character(1)` | Compiles pattern from R |
144//! | `url` | `Url`, `Vec<Url>` | `character` | Validated URLs |
145//! | `time` | `OffsetDateTime`, `Date` | `POSIXct`, `Date` | Date/time conversions |
146//! | `jiff` | `Timestamp`, `Zoned`, civil types | R date/time classes | IANA timezone-aware conversions |
147//! | `ordered-float` | `OrderedFloat<f64>` | `numeric` | NaN-orderable floats |
148//! | `num-bigint` | `BigInt`, `BigUint` | `character` | Arbitrary precision via strings |
149//! | `rust_decimal` | `Decimal` | `character` | Fixed-point decimals |
150//! | `num-complex` | `Complex<f64>` | `complex` | Native R complex support |
151//! | `indexmap` | `IndexMap<String, T>` | named `list` | Preserves insertion order |
152//! | `bitflags` | `RFlags<T>` | `integer` | Bitflags ↔ integer |
153//! | `bitvec` | `RBitVec` | `logical` | Bit vectors ↔ logical |
154//! | `tinyvec` | `TinyVec<[T; N]>`, `ArrayVec<[T; N]>` | vectors | Small-vector optimization |
155//!
156//! ### Matrix & Array Libraries
157//!
158//! | Feature | Types | Conversions |
159//! |---------|-------|-------------|
160//! | `ndarray` | `Array1`–`Array6`, `ArrayD`, views | R vectors/matrices ↔ ndarray |
161//! | `nalgebra` | `DVector`, `DMatrix` | R vectors/matrices ↔ nalgebra |
162//! | `blas-lapack` | `linalg::{matrix_product, solve}`, `sys::{dgemm_, dgesv_}` | R's own BLAS/LAPACK (links `$(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)`) |
163//!
164//! ### Serialization
165//!
166//! | Feature | Traits/Modules | Description |
167//! |---------|----------------|-------------|
168//! | `serde` | `RSerializeNative`, `RDeserializeNative` | Direct Rust ↔ R native serialization |
169//! | `serde_json` | `RSerialize`, `RDeserialize` | JSON string serialization (includes `serde`) |
170//! | `borsh` | `Borsh<T>` | Binary serialization ↔ raw vectors via Borsh |
171//!
172//! ### Adapter Traits (Generic Operations)
173//!
174//! | Feature | Traits | Use Case |
175//! |---------|--------|----------|
176//! | `num-traits` | `RNum`, `RSigned`, `RFloat` | Generic numeric operations |
177//! | `bytes` | `RBuf`, `RBufMut` | Byte buffer operations |
178//!
179//! ### Text & Data Processing
180//!
181//! | Feature | Types/Functions | Description |
182//! |---------|-----------------|-------------|
183//! | `aho-corasick` | `AhoCorasick`, `aho_compile` | Fast multi-pattern string search |
184//! | `toml` | `TomlValue`, `toml_from_str` | TOML parsing and serialization |
185//! | `tabled` | `table_to_string` | ASCII/Unicode table formatting |
186//! | `sha2` | `sha256_str`, `sha512_bytes` | Cryptographic hashing |
187//! | `blake3` | `blake3_str`, `blake3_bytes` | BLAKE3 hashing (fast, 32-byte digests) |
188//! | `md5` | `md5_str`, `md5_bytes` | MD5 hashing (interop only — broken crypto) |
189//! | `globset` | `GlobSet`, `build_globset` | Shell-style glob matching (path-aware) |
190//! | `zstd` | `zstd_compress`, `zstd_decompress` | zstd whole-buffer compression |
191//!
192//! ### Random Number Generation
193//!
194//! | Feature | Types | Description |
195//! |---------|-------|-------------|
196//! | `rand` | `RRng`, `RDistributions` | Wraps R's RNG with `rand` traits |
197//! | `rand_distr` | Re-exports `rand_distr` | Additional distributions (Normal, Exp, etc.) |
198//!
199//! ### Binary Data
200//!
201//! | Feature | Types | Description |
202//! |---------|-------|-------------|
203//! | `raw_conversions` | `Raw<T>`, `RawSlice<T>` | POD types ↔ raw vectors via bytemuck |
204//!
205//! ### Project-wide Defaults (mutually exclusive where noted)
206//!
207//! | Feature | Description |
208//! |---------|-------------|
209//! | `r6-default` | Default class system: R6 (mutually exclusive with `s7-default`) |
210//! | `s7-default` | Default class system: S7 (mutually exclusive with `r6-default`) |
211//! | `strict-default` | Default to strict mode for lossy integer conversions |
212//! | `coerce-default` | Default to coerce mode for type conversions |
213//! | `no-preconditions-default` | Drop the R-side type checks by default (`preconditions` keeps them per item) |
214//!
215//! ### Development / Diagnostics
216//!
217//! | Feature | Description |
218//! |---------|-------------|
219//! | `doc-lint` | Warn on roxygen doc comment mismatches (enabled by default) |
220//! | `macro-coverage` | Expose macro coverage test module for `cargo expand` auditing |
221//! | `growth-debug` | Track and report collection growth events (zero-cost when off) |
222//! | `full-integrations` | Every optional dependency integration (maintenance aggregate) |
223//! | `full-codegen` | Codegen/runtime selectors using `r6-default` (maintenance aggregate) |
224//! | `full-codegen-s7` | Codegen/runtime selectors using `s7-default` (maintenance aggregate) |
225//! | `full` | Integrations + `full-codegen` + diagnostics for local checks |
226// Re-export linkme for use by generated code (distributed_slice entries)
227#[doc(hidden)]
228pub use linkme;
229
230// Procedural macros (re-exported from miniextendr-macros)
231#[doc(hidden)]
232pub use miniextendr_macros::__mx_trait_impl_expand;
233#[doc(inline)]
234pub use miniextendr_macros::AllEqual;
235#[doc(inline)]
236pub use miniextendr_macros::ExternalPtr;
237#[doc(inline)]
238pub use miniextendr_macros::impl_typed_external;
239#[doc(inline)]
240pub use miniextendr_macros::list;
241#[doc(inline)]
242pub use miniextendr_macros::miniextendr;
243#[doc(inline)]
244pub use miniextendr_macros::miniextendr_init;
245#[doc(inline)]
246pub use miniextendr_macros::r_ffi_checked;
247#[doc(inline)]
248pub use miniextendr_macros::reexport;
249#[doc(inline)]
250pub use miniextendr_macros::typed_dataframe;
251#[doc(inline)]
252pub use miniextendr_macros::typed_list;
253#[doc(inline)]
254pub use miniextendr_macros::{IsNA, RNativeType};
255// Note: RFactor derive macro is re-exported - it shares the name with the RFactor trait
256// but they're in different namespaces (derive macros vs types/traits)
257#[cfg(feature = "vctrs")]
258#[doc(inline)]
259pub use miniextendr_macros::{PreferVctrs, Vctrs};
260// Note: MatchArg derive macro is re-exported - it shares the name with the MatchArg trait
261// but they're in different namespaces (derive macros vs types/traits), same as RFactor.
262// The same applies to the `IntoR` and `TryFromSexp` derive macros, which share names with
263// the `IntoR` / `TryFromSexp` traits — `#[derive(IntoR)]` (macro namespace) and the trait
264// (type namespace) coexist, exactly like serde's `Serialize`. `RCondition` follows
265// suit: the enum and the derive are re-exported together from `condition`.
266#[doc(inline)]
267pub use miniextendr_macros::{
268 Altrep, AltrepComplex, AltrepInteger, AltrepList, AltrepLogical, AltrepRaw, AltrepReal,
269 AltrepString, DataFrameRow, IntoList, IntoR, MatchArg, PreferExternalPtr, PreferList,
270 PreferRNativeType, RFactor, TryFromList, TryFromSexp,
271};
272
273pub mod altrep;
274pub mod altrep_bridge;
275pub mod altrep_data;
276pub mod altrep_ext;
277pub mod altrep_impl;
278pub mod altrep_sexp;
279pub mod altrep_traits;
280
281// Re-export for backward compatibility - RegisterAltrep was moved from altrep_registration to altrep
282#[doc(hidden)]
283pub mod altrep_registration {
284 pub use crate::altrep::RegisterAltrep;
285}
286/// Core type vocabulary for R values: `SEXPTYPE`, `R_xlen_t`, `Rcomplex`,
287/// `RLogical`, `Rboolean`, `RNativeType`, `cetype_t`.
288pub mod sexp_types;
289
290/// The `SEXP` newtype and inherent methods.
291pub mod sexp;
292
293/// `SexpExt` and `PairListExt` — the ergonomic extension traits on `SEXP`.
294pub mod sexp_ext;
295
296/// Raw R FFI bindings — `extern "C-unwind"` blocks for `Rf_*` / `R_*` /
297/// `INTEGER` / etc., plus the ALTREP method type aliases under
298/// [`sys::altrep`]. The escape hatch for code that genuinely needs the raw
299/// R C API.
300///
301/// **Almost no user code should reach into this module.** The framework
302/// expects you to use the crate-root re-exports for the type vocabulary
303/// ([`SEXP`], [`SexpExt`], [`SEXPTYPE`], [`R_xlen_t`], …) and the
304/// higher-level safe wrappers ([`IntoR`], [`TryFromSexp`],
305/// [`with_r_thread`], [`unwind_protect::with_r_unwind_protect`],
306/// the `#[miniextendr]` proc-macro). `sys::` is only here so those
307/// wrappers — and the rare hand-rolled FFI in tests or benchmarks — have
308/// something to call.
309pub mod sys;
310
311// Crate-root re-exports for the ergonomic API surface.
312pub use sexp::{SEXP, SEXPREC};
313pub use sexp_ext::{PairListArgs, PairListExt, SexpExt};
314pub use sexp_types::{
315 IsNA, R_CFinalizer_t, R_xlen_t, RLogical, RNativeType, Rboolean, Rbyte, Rcomplex, SEXPTYPE,
316 cetype_t,
317};
318
319pub mod registry;
320
321/// Host-time generator of `wasm_registry.rs` — the WASM-side replacement for
322/// linkme. See the module for full rationale.
323///
324/// Host-only — the writer reads the live linkme distributed slices to format
325/// `wasm_registry.rs`, and linkme isn't available on wasm32 anyway.
326#[cfg(not(target_arch = "wasm32"))]
327pub mod wasm_registry_writer;
328
329// Re-export high-level ALTREP data traits
330pub use altrep_data::{
331 AltComplexData,
332 AltIntegerData,
333 AltListData,
334 AltLogicalData,
335 AltRawData,
336 AltRealData,
337 AltStringData,
338 AltrepBuffer,
339 AltrepDataptr,
340 AltrepExtract,
341 AltrepIteratorExt,
342 AltrepIteratorItem,
343 AltrepLen,
344 // Iterator-backed ALTREP types (R-native)
345 IterComplexData,
346 // Iterator-backed ALTREP types (with Coerce support)
347 IterIntCoerceData,
348 IterIntData,
349 IterIntFromBoolData,
350 IterListData,
351 IterLogicalData,
352 IterRLogicalData,
353 IterRawData,
354 IterRealCoerceData,
355 IterRealData,
356 IterState,
357 IterStringData,
358 Logical,
359 Sortedness,
360 // Sparse iterator-backed ALTREP types (compute-on-access)
361 SparseIterComplexData,
362 SparseIterIntData,
363 SparseIterLogicalData,
364 SparseIterRawData,
365 SparseIterRealData,
366 SparseIterState,
367 // Streaming ALTREP types (chunk-cached reader closures)
368 StreamingIntData,
369 StreamingRealData,
370 // Windowed iterator-backed ALTREP types
371 WindowedIterIntData,
372 WindowedIterRealData,
373 WindowedIterState,
374};
375// Re-export RBase enum, AltrepGuard, and AltrepSexp
376pub use altrep::RBase;
377pub use altrep_sexp::{AltrepSexp, ensure_materialized};
378pub use altrep_traits::AltrepGuard;
379
380// ALTREP package name global - set by C entrypoint before ALTREP registration
381// This is a pointer to a null-terminated C string provided by C code.
382// Default: c"unknown" for safety if not set.
383use std::sync::atomic::{AtomicPtr, Ordering};
384static ALTREP_PKG_NAME_PTR: AtomicPtr<std::ffi::c_char> =
385 AtomicPtr::new(c"unknown".as_ptr().cast_mut());
386
387/// Returns the current ALTREP package name as a C string pointer.
388/// This is set by the C entrypoint before ALTREP registration.
389#[doc(hidden)]
390pub struct AltrepPkgName;
391
392impl AltrepPkgName {
393 /// Get the package name pointer.
394 #[inline]
395 pub fn as_ptr() -> *const std::ffi::c_char {
396 ALTREP_PKG_NAME_PTR.load(Ordering::Acquire)
397 }
398}
399
400/// Opaque handle for ALTREP package name.
401/// Use `ALTREP_PKG_NAME.as_ptr()` to get the C string pointer.
402#[doc(hidden)]
403pub static ALTREP_PKG_NAME: AltrepPkgName = AltrepPkgName;
404
405/// Set the ALTREP package name. Called from C entrypoint.
406/// # Safety
407/// The provided pointer must point to a valid null-terminated C string
408/// that lives for the duration of the R session.
409///
410/// The strict requirement is narrower: R copies the bytes via `install()`
411/// inside each `R_make_alt*_class` call that consults this global (see
412/// `RegisterClass` in R's `src/main/altrep.c`), so the pointer only has to
413/// remain valid across those calls. We keep the session-lifetime contract
414/// because we don't track which registrations are still pending; a string
415/// literal passed from C satisfies both.
416#[doc(hidden)]
417#[unsafe(no_mangle)]
418pub unsafe extern "C" fn miniextendr_set_altrep_pkg_name(name: *const std::ffi::c_char) {
419 let name = if name.is_null() {
420 c"unknown".as_ptr()
421 } else {
422 name
423 };
424 ALTREP_PKG_NAME_PTR.store(name.cast_mut(), Ordering::Release);
425}
426
427// DllInfo global — stored during package_init, used by ALTREP class registration.
428// R needs DllInfo to associate ALTREP classes with their package for serialization.
429// Without it, readRDS in a fresh session can't find the class.
430static ALTREP_DLL_INFO: AtomicPtr<std::ffi::c_void> = AtomicPtr::new(std::ptr::null_mut());
431
432/// Get the stored DllInfo pointer for ALTREP class registration.
433#[doc(hidden)]
434pub fn altrep_dll_info() -> *mut sys::DllInfo {
435 ALTREP_DLL_INFO.load(Ordering::Acquire).cast()
436}
437
438/// Store the DllInfo pointer during package init.
439#[doc(hidden)]
440pub fn set_altrep_dll_info(dll: *mut sys::DllInfo) {
441 ALTREP_DLL_INFO.store(dll.cast(), Ordering::Release);
442}
443
444mod tuple_macros;
445
446pub mod from_r;
447pub mod into_r;
448pub mod into_r_error;
449pub use into_r::{Altrep, IntoR, IntoRAltrep};
450/// Container conversions for newtypes (`#[derive(TryFromSexp)]` /
451/// `#[derive(IntoR)]`) and string-parsed types
452/// (`try_from_sexp_via_str_parse!`). See the module docs, #844 and #1766.
453pub mod newtype;
454pub use into_r_error::IntoRError;
455pub use newtype::{IntoRNewtype, IntoRVecElement, TryFromSexpElement};
456pub mod into_r_as;
457pub use into_r_as::{IntoRAs, StorageCoerceError};
458pub mod pump;
459pub mod unwind_protect;
460
461// R's main thread (`with_r_thread`, `is_r_main_thread`) plus advanced
462// stack-configuration utilities; the latter are not permission for off-main
463// R API use
464pub mod thread;
465pub use thread::{is_r_main_thread, miniextendr_runtime_init, with_r_thread};
466
467// Collection growth debug instrumentation (diagnostics)
468#[cfg(feature = "growth-debug")]
469pub mod growth_debug;
470
471/// Track a collection growth (reallocation) event.
472///
473/// When the `growth-debug` feature is enabled, increments a thread-local counter
474/// for the named collection. When disabled, compiles to a no-op.
475///
476/// # Example
477///
478/// ```ignore
479/// let old_cap = vec.capacity();
480/// vec.push(item);
481/// if vec.capacity() != old_cap {
482/// track_growth!("my_vec");
483/// }
484/// ```
485#[cfg(feature = "growth-debug")]
486#[macro_export]
487macro_rules! track_growth {
488 ($name:expr) => {
489 $crate::growth_debug::record_growth($name)
490 };
491}
492
493/// Track a collection growth (reallocation) event.
494///
495/// No-op when `growth-debug` feature is disabled.
496#[cfg(not(feature = "growth-debug"))]
497#[macro_export]
498macro_rules! track_growth {
499 ($name:expr) => {};
500}
501
502/// Print and reset all growth counters.
503///
504/// When the `growth-debug` feature is enabled, prints all tracked growth events
505/// to stderr and resets the counters. When disabled, compiles to a no-op.
506#[cfg(feature = "growth-debug")]
507#[macro_export]
508macro_rules! report_growth {
509 () => {
510 $crate::growth_debug::report_and_reset()
511 };
512}
513
514/// Print and reset all growth counters.
515///
516/// No-op when `growth-debug` feature is disabled.
517#[cfg(not(feature = "growth-debug"))]
518#[macro_export]
519macro_rules! report_growth {
520 () => {};
521}
522
523/// Parse and evaluate **runtime** R source from Rust.
524///
525/// `r_str!` is sugar around [`expression::r_eval_str`]. It is the right tool
526/// when the R code is genuinely dynamic — built with `format!`, derived from
527/// user input, or otherwise not known at compile time. For code you can write
528/// literally, prefer [`r!`](crate::r), which gives a cheap compile-time
529/// sanity check on the token stream.
530///
531/// The argument is any expression evaluating to something `AsRef<str>`
532/// (`&str`, `String`, `&String`, …). It is parsed with `R_ParseVector` and
533/// evaluated with `Rf_eval`, with every intermediate SEXP protected and the
534/// parse status checked, so a syntax error becomes an `Err`, never a segfault
535/// or silent wrong answer.
536///
537/// # Forms
538///
539/// - `r_str!(code)` — evaluate in `R_GlobalEnv`.
540/// - `r_str!(code, env = e)` — evaluate in the environment SEXP `e`.
541///
542/// Both forms evaluate to `Result<SEXP, REvalError>`; the `SEXP` is **unprotected**
543/// (protect it before further allocations).
544///
545/// # Safety
546///
547/// Expands to an `unsafe` block. Must be reached from the R
548/// main thread — the underlying FFI is `#[r_ffi_checked]`, so a call from
549/// another thread panics before it reaches R.
550///
551/// # Example
552///
553/// ```ignore
554/// let obj = "mtcars";
555/// let code = format!("summary({obj})");
556/// let summary = r_str!(&code)?; // in R_GlobalEnv
557/// let three = r_str!("1L + 2L")?;
558/// let in_env = r_str!("x + 1", env = my_env)?;
559/// ```
560#[macro_export]
561macro_rules! r_str {
562 ($code:expr $(,)?) => {
563 unsafe {
564 $crate::expression::r_eval_str(
565 ::core::convert::AsRef::<str>::as_ref(&$code),
566 $crate::sys::R_GlobalEnv,
567 )
568 }
569 };
570 ($code:expr, env = $env:expr $(,)?) => {
571 unsafe {
572 $crate::expression::r_eval_str(::core::convert::AsRef::<str>::as_ref(&$code), $env)
573 }
574 };
575}
576
577/// Evaluate R code written as **Rust tokens**, validated at compile time.
578///
579/// `r!` takes a single R expression as a token stream, `stringify!`s it into a
580/// static R source string at build time, and evaluates it via
581/// [`expression::r_eval_str`] (the same protect-safe parse + eval path as
582/// [`r_str!`]).
583///
584/// # What you get today
585///
586/// Because the argument is a Rust token tree, the Rust front-end already
587/// rejects **unbalanced delimiters** (`r!(f(1, 2)` won't compile) and
588/// lexically invalid tokens before R ever sees the string — a cheap
589/// compile-time guard over the pure-runtime [`r_str!`]. The
590/// source is lowered to a `&'static str` (`stringify!`), so there is no
591/// `format!` allocation at the call site.
592///
593/// This proc-macro additionally validates a conservative subset of known-bad
594/// R syntax constructs (trailing binary operators, consecutive non-unary
595/// binary operators, bare `if`/`while`/`for` without a body, etc.) and emits
596/// a precise compile error pointing at the offending token. Empty (missing)
597/// call arguments — `f(, x)`, `matrix(, 2, 2)` — are valid R and pass.
598///
599/// # What is deferred
600///
601/// Direct `Rf_lang*` call-tree lowering (skipping the runtime parser entirely)
602/// is tracked as a follow-up — see issue #938 (item 2). Until then `r!` parses
603/// its static string at first evaluation, exactly like `r_str!`.
604///
605/// # Non-goals
606///
607/// A complete R grammar validator is not achievable over Rust tokens:
608/// - Single-quoted strings (`'hello'`) and backtick-quoted names (`` `foo` ``)
609/// already die at the Rust lexer — nothing to validate.
610/// - `%op%` tokenises as `%`, ident, `%` and is accepted without analysis.
611/// - Anything the validator cannot confidently classify as wrong passes through
612/// unvalidated (conservative reject-only-known-bad design).
613///
614/// # Forms
615///
616/// - `r!(R tokens…)` — evaluate in `R_GlobalEnv`.
617/// - `r!(env: e; R tokens…)` — evaluate in the environment SEXP `e`. The
618/// leading `env: <expr> ;` is consumed as Rust, the rest is R source. (The
619/// `;` separator is used instead of a trailing `, env =` because R source is
620/// a free token stream — a trailing keyword can't be reliably split off it.)
621///
622/// Both evaluate to `Result<SEXP, REvalError>`; the `SEXP` is **unprotected**.
623///
624/// For genuinely dynamic code, use [`r_str!`] instead.
625///
626/// # Note on `stringify!` spacing
627///
628/// `stringify!` normalises whitespace (`a+b` and `a + b` both stringify to
629/// `a + b`) but preserves token order and literal contents, which is all R's
630/// parser needs. String literals keep their quotes.
631///
632/// # Safety
633///
634/// Expands to an `unsafe` block; see [`r_str!`].
635///
636/// # Example
637///
638/// ```ignore
639/// let three = r!(1L + 2L)?;
640/// let rows = r!(getFromNamespace(".theoph_rows", "dataframeflows")())?;
641/// let in_env = r!(env: my_env; x + 1)?;
642/// ```
643#[doc(inline)]
644pub use miniextendr_macros::r;
645
646// `indicatif` progress integration (R console)
647#[cfg(feature = "indicatif")]
648pub mod progress;
649#[cfg(feature = "indicatif")]
650pub use indicatif;
651
652// Legacy R-oriented stack sizing (always available; not an off-main R bridge)
653#[cfg(windows)]
654pub use thread::WINDOWS_R_STACK_SIZE;
655pub use thread::{DEFAULT_R_STACK_SIZE, RThreadBuilder};
656
657// Legacy process-global stack controls (requires nonapi; removal tracked in #1352)
658#[cfg(feature = "nonapi")]
659pub use thread::{StackCheckGuard, scope_with_r, spawn_with_r, with_stack_checking_disabled};
660
661// Panic telemetry hook for structured panic→R-error diagnostics
662pub mod panic_telemetry;
663
664// Unified FFI guard for catching panics at Rust-R boundaries
665pub mod ffi_guard;
666pub use ffi_guard::{GuardMode, guarded_ffi_call, guarded_ffi_call_with_fallback};
667
668// The unified owned data.frame type + conversion trait family
669pub mod dataframe;
670pub use dataframe::{
671 BuiltDataFrame, ColumnarFrame, DataFrame, DataFrameError, DataFrameShape, FromDataFrame,
672 GroupDeclaration, GroupKey, GroupedDataFrame, IntoDataFrame, IntoDataFrameSplit, RealKey,
673 SplitResults, group_rows,
674};
675
676// Closure-per-column DataFrame builder (parallel fill with `rayon`, serial
677// otherwise). Available regardless of the `rayon` feature (#1055).
678pub mod dataframe_builder;
679pub use dataframe_builder::RDataFrameBuilder;
680
681// Strict conversion helpers for #[miniextendr(strict)]
682pub mod strict;
683
684// Cached R class attribute SEXPs (POSIXct, Date, data.frame, etc.)
685pub mod cached_class;
686
687// Tagged condition value transport for the Rust→R boundary
688pub mod error_value;
689
690// Error handling helpers (r_warning, r_print!, r_println! macros)
691pub mod error;
692pub use error::r_warning;
693
694// RNG (random number generation) utilities
695pub mod rng;
696pub use rng::{RngGuard, with_rng};
697
698// Re-export from_r
699pub use from_r::{
700 SexpClassError, SexpError, SexpLengthError, SexpNaError, SexpTypeError, TryFromRoot,
701 TryFromSexp,
702};
703
704// Encoding / locale probing (mainly for debugging). The module is always
705// compiled; the symbols that reference non-API locale state from R's `Defn.h`
706// (`utf8locale`, `mbcslocale`, `known_to_be_latin1`) are gated inside the
707// module behind `#[cfg(feature = "nonapi")]` so a default build never links
708// them. Only R-exported symbols may be declared there — hidden ones abort
709// dyn.load (see sys::nonapi_encoding).
710pub mod encoding;
711
712// Expression evaluation helpers (RSymbol, RCall, REnv)
713pub mod expression;
714pub use expression::{RCall, REnv, REvalError, RSymbol, r_eval_str, r_eval_str_global};
715
716/// Reading R options (`getOption()`) from Rust.
717pub mod options;
718pub use options::get_option;
719
720// S4 slot access and class checking helpers
721pub mod s4_helpers;
722
723pub mod backtrace;
724
725/// Shared truthiness parsing for boolean-ish environment-variable flags.
726pub(crate) mod env_flag;
727
728pub mod coerce;
729pub use coerce::{Coerce, CoerceError, Coerced, TryCoerce};
730
731/// Traits for R's `as.<class>()` coercion functions.
732///
733/// This module provides traits for implementing R's generic coercion methods
734/// (`as.data.frame()`, `as.list()`, `as.character()`, etc.) for Rust types
735/// wrapped in [`ExternalPtr`](struct@ExternalPtr).
736///
737/// See the [`r_coerce`] module documentation for usage examples.
738pub mod r_coerce;
739pub use r_coerce::{
740 // Core coercion traits (R's `as.<class>()` generics)
741 RCoerceCharacter,
742 RCoerceComplex,
743 RCoerceDataFrame,
744 RCoerceDate,
745 RCoerceEnvironment,
746 // Error type
747 RCoerceError,
748 RCoerceFactor,
749 RCoerceFunction,
750 RCoerceInteger,
751 RCoerceList,
752 RCoerceLogical,
753 RCoerceMatrix,
754 RCoerceNumeric,
755 RCoercePOSIXct,
756 RCoerceRaw,
757 RCoerceVector,
758 // Helpers
759 SUPPORTED_AS_GENERICS,
760 is_supported_as_generic,
761};
762
763pub mod condition;
764pub use condition::{ArgError, AsRError, RCondition};
765pub mod deferred_condition;
766pub use deferred_condition::{defer_condition, defer_message, defer_warning};
767pub mod convert;
768pub mod dots;
769pub mod list;
770pub mod missing;
771/// Return-visibility markers (`Invisible<T>` / `Visible<T>`).
772pub mod visibility;
773pub use visibility::{Invisible, Visible};
774/// The `NULL`-on-`None` optional (`Nullable<T>`): a return, an `#[r_data]` field, or an
775/// argument read as `Option<T>`.
776pub mod nullable;
777pub use nullable::Nullable;
778/// Condition-call markers (`Call` / `CallerCall`) for `#[miniextendr]` parameters.
779pub mod call_marker;
780pub use call_marker::{Call, CallerCall};
781/// The argument-count marker (`NArgs`) for `#[miniextendr]` parameters.
782pub mod nargs;
783pub use nargs::NArgs;
784/// Unevaluated-argument markers (`Quoted` / `Quosure`) for `#[miniextendr]` parameters.
785pub mod quoted;
786pub use quoted::{Quosure, Quoted};
787pub mod lazy_dots;
788pub use lazy_dots::LazyDots;
789/// Precondition markers (`Checked<T>` / `Unchecked<T>`) for `#[miniextendr]` parameters.
790pub mod precondition_marker;
791pub use precondition_marker::{Checked, Unchecked};
792/// `NonNa<T>`: a value that holds no R `NA`, a `#[miniextendr]` parameter marker.
793pub mod non_na;
794pub use non_na::{MaybeNa, NonNa};
795
796/// Explicit R class-system return markers.
797pub mod wrap_as;
798pub use wrap_as::{
799 ConvertFrom, ConvertTo, WrapAsEnv, WrapAsR6, WrapAsS3, WrapAsS4, WrapAsS7, WrapAsVctrs,
800};
801pub mod named_vector;
802pub mod rcow;
803pub mod rvalue;
804pub use rvalue::RValue;
805pub mod strvec;
806pub mod typed_list;
807pub use convert::{
808 AsCharacter, AsCharacterVec, AsDataFrame, AsDataFrameExt, AsDisplay, AsDisplayVec,
809 AsExternalPtr, AsExternalPtrExt, AsFromStr, AsFromStrVec, AsList, AsListExt, AsNamedList,
810 AsNamedListExt, AsNamedVector, AsNamedVectorExt, AsNumeric, AsNumericVec, AsRNative,
811 AsRNativeExt, Collect, CollectNA, CollectNAInt, CollectStrings, ColumnSource,
812};
813#[cfg(feature = "vctrs")]
814pub use convert::{AsVctrs, AsVctrsExt};
815pub use into_r::Lazy;
816pub use list::{
817 BuiltList, IntoList, List, ListAccumulator, ListBuilder, ListMut, NamedList, NamedListBuilder,
818 TryFromList, collect_list,
819};
820pub use missing::{Missing, is_missing_arg};
821pub use named_vector::{AtomicElement, NamedVector};
822pub use rcow::{RBorrow, RCow};
823pub use strvec::{
824 ProtectedStrVec, ProtectedStrVecCowIter, ProtectedStrVecIter, StrVec, StrVecBuilder,
825 StrVecCowIter, StrVecIter,
826};
827pub use typed_list::{
828 TypeSpec, TypedEntry, TypedList, TypedListError, TypedListSpec, actual_type_string,
829 sexptype_name, validate_list,
830};
831
832// External pointer module - Box-like owned pointer wrapping R's EXTPTRSXP
833pub mod externalptr;
834
835// Matrix product / linear solve through R's own BLAS and LAPACK
836#[cfg(feature = "blas-lapack")]
837pub mod linalg;
838
839// Connection framework (unstable R API - use with caution)
840#[cfg(feature = "connections")]
841pub mod connection;
842// txtProgressBar handle — drives utils::txtProgressBar from Rust
843#[cfg(feature = "connections")]
844pub mod txt_progress_bar;
845pub use externalptr::{
846 ErasedExternalPtr,
847 ExternalPtr,
848 ExternalPtrMut,
849 ExternalPtrRef,
850 ExternalSlice,
851 IntoExternalPtr,
852 TypedExternal,
853 // ALTREP helpers (checked)
854 altrep_data1_as,
855 // ALTREP helpers (unchecked - for performance-critical callbacks)
856 altrep_data1_as_unchecked,
857 altrep_data1_mut,
858 altrep_data1_mut_unchecked,
859 altrep_data2_as,
860 altrep_data2_as_unchecked,
861};
862
863// TypedExternal implementations for std types
864pub mod externalptr_std;
865
866// GC protection toolkit (PROTECT stack RAII wrappers)
867pub mod gc_protect;
868pub use gc_protect::{
869 OwnedProtect, ProtectIndex, ProtectScope, Protected, Protector, ReprotectSlot, Root,
870};
871
872// One owned precious-list root (R_PreserveObject / R_ReleaseObject)
873pub mod preserved;
874pub use preserved::Preserved;
875
876// VECSXP pool with generational keys (slotmap-backed)
877pub mod protect_pool;
878pub use protect_pool::{ProtectKey, ProtectPool};
879
880// Reference-counted GC protection (BTreeMap + VECSXP backing)
881pub mod refcount_protect;
882pub use refcount_protect::{ArenaGuard, RefCountedArena, ThreadLocalArena};
883
884pub mod allocator;
885pub use allocator::RAllocator;
886
887// region: Trait ABI Support
888//
889// Cross-package trait dispatch using a stable C ABI.
890// See `trait_abi` module docs for details.
891
892/// ABI types for cross-package trait dispatch.
893///
894/// This module defines the stable, C-compatible types used for runtime trait
895/// dispatch across R package boundaries.
896pub mod abi;
897
898/// C-callable mx_abi functions (mx_wrap, mx_get, mx_query, mx_abi_register).
899///
900/// These are registered via `R_RegisterCCallable` during package init and
901/// loaded by consumer packages via `R_GetCCallable`.
902pub mod mx_abi;
903
904pub mod init;
905
906/// Runtime support for trait ABI operations.
907///
908/// Provides C-callable loading and type conversion helpers for trait ABI support.
909pub mod trait_abi;
910
911/// vctrs class construction and trait support.
912///
913/// Provides helpers for building vctrs-compatible R objects and traits
914/// for describing vctrs class metadata from Rust types.
915///
916/// Enable with `features = ["vctrs"]`.
917#[cfg(feature = "vctrs")]
918pub mod vctrs;
919#[cfg(feature = "vctrs")]
920pub use vctrs::{
921 IntoVctrs, VctrsBuildError, VctrsClass, VctrsKind, VctrsListOf, VctrsRecord, new_list_of,
922 new_rcrd, new_vctr,
923};
924
925// Re-export key ABI types at crate root for convenience
926pub use abi::{mx_base_vtable, mx_erased, mx_meth, mx_tag};
927pub use trait_abi::TraitView;
928// endregion
929
930// region: Marker Traits
931//
932// Marker traits for types derived with proc-macros.
933// These enable compile-time identification and blanket implementations.
934
935/// Marker traits for proc-macro derived types.
936pub mod markers;
937// endregion
938
939// region: Adapter Traits
940//
941// Built-in adapter traits with blanket implementations for standard library traits.
942// These allow any Rust type implementing Debug, Display, Hash, Ord, etc. to be
943// exposed to R without boilerplate.
944
945/// Built-in adapter traits for std library traits.
946///
947/// Provides [`RDebug`], [`RDisplay`], [`RHash`], [`ROrd`], [`RPartialOrd`],
948/// [`RError`], [`RFromStr`], [`RClone`], [`RCopy`], [`RDefault`], [`RIterator`],
949/// [`RExtend`], [`RFromIter`], [`RToVec`], and [`RMakeIter`] with blanket
950/// implementations where possible. Methods that share a name with a std
951/// method are `r_`-prefixed in Rust and keep the std name in R, so importing
952/// these traits leaves std calls alone. See module docs for usage.
953///
954/// [`RDebug`]: adapter_traits::RDebug
955/// [`RDisplay`]: adapter_traits::RDisplay
956/// [`RHash`]: adapter_traits::RHash
957/// [`ROrd`]: adapter_traits::ROrd
958/// [`RPartialOrd`]: adapter_traits::RPartialOrd
959/// [`RError`]: adapter_traits::RError
960/// [`RFromStr`]: adapter_traits::RFromStr
961/// [`RClone`]: adapter_traits::RClone
962/// [`RCopy`]: adapter_traits::RCopy
963/// [`RDefault`]: adapter_traits::RDefault
964/// [`RIterator`]: adapter_traits::RIterator
965/// [`RExtend`]: adapter_traits::RExtend
966/// [`RFromIter`]: adapter_traits::RFromIter
967/// [`RToVec`]: adapter_traits::RToVec
968/// [`RMakeIter`]: adapter_traits::RMakeIter
969pub mod adapter_traits;
970pub use adapter_traits::{
971 RClone, RCopy, RDebug, RDefault, RDisplay, RError, RExtend, RFromIter, RFromStr, RHash,
972 RIterator, RMakeIter, ROrd, RPartialOrd, RToVec,
973};
974
975/// This is used to ensure the macros of `miniextendr-macros` treat this crate as a "user crate"
976/// atleast in the `macro_coverage`
977#[doc(hidden)]
978extern crate self as miniextendr_api;
979
980#[cfg(feature = "macro-coverage")]
981#[doc(hidden)]
982pub mod macro_coverage;
983
984/// The crate-root marker `miniextendr_init!` defines in a package crate, for
985/// the `#[miniextendr]` items of `macro_coverage`: under `serde` their `Err`
986/// arms look up `serde_error_shape!` declarations by it. None is declared.
987#[cfg(all(feature = "macro-coverage", feature = "serde"))]
988enum __MiniextendrInitMarker {}
989// endregion
990
991// region: Optional integrations with external crates (feature-gated)
992//
993// All optional feature integrations are organized in the `optionals` module.
994// Types are re-exported at crate root for backwards compatibility.
995
996/// Optional feature integrations with third-party crates.
997///
998/// This module contains all feature-gated integrations with external crates.
999/// Each submodule is only compiled when its corresponding feature is enabled.
1000/// See the [module documentation][optionals] for a complete list of available features.
1001pub mod optionals;
1002
1003// Re-export optional types at crate root for backwards compatibility
1004#[cfg(feature = "rayon")]
1005pub use optionals::parallel;
1006#[cfg(feature = "rayon")]
1007pub use optionals::rayon_bridge;
1008#[cfg(feature = "rayon")]
1009pub use optionals::{RParallelExtend, RParallelIterator};
1010
1011#[cfg(feature = "rand")]
1012pub use optionals::rand;
1013#[cfg(feature = "rand_distr")]
1014pub use optionals::rand_distr;
1015#[cfg(feature = "rand")]
1016pub use optionals::rand_impl;
1017#[cfg(feature = "rand")]
1018pub use optionals::{RDistributionOps, RDistributions, RRng, RRngOps};
1019
1020#[cfg(feature = "either")]
1021pub use optionals::either_impl;
1022#[cfg(feature = "either")]
1023pub use optionals::{Either, Left, Right};
1024
1025#[cfg(feature = "ndarray")]
1026pub use optionals::ndarray_impl;
1027#[cfg(feature = "ndarray")]
1028pub use optionals::{
1029 ArcArray1, ArcArray2, Array0, Array1, Array2, Array3, Array4, Array5, Array6, ArrayD,
1030 ArrayView0, ArrayView1, ArrayView2, ArrayView3, ArrayView4, ArrayView5, ArrayView6, ArrayViewD,
1031 ArrayViewMut0, ArrayViewMut1, ArrayViewMut2, ArrayViewMut3, ArrayViewMut4, ArrayViewMut5,
1032 ArrayViewMut6, ArrayViewMutD, Ix0, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn, RNdArrayOps, RNdIndex,
1033 RNdSlice, RNdSlice2D, ShapeBuilder,
1034};
1035
1036#[cfg(feature = "nalgebra")]
1037pub use optionals::nalgebra_impl;
1038#[cfg(feature = "nalgebra")]
1039pub use optionals::{DMatrix, DVector, RMatrixOps, RVectorOps, SMatrix, SVector};
1040
1041#[cfg(feature = "num-bigint")]
1042pub use optionals::num_bigint_impl;
1043#[cfg(feature = "num-bigint")]
1044pub use optionals::{BigInt, BigUint, RBigIntBitOps, RBigIntOps, RBigUintBitOps, RBigUintOps};
1045
1046#[cfg(feature = "rust_decimal")]
1047pub use optionals::rust_decimal_impl;
1048#[cfg(feature = "rust_decimal")]
1049pub use optionals::{Decimal, RDecimalOps};
1050
1051#[cfg(feature = "ordered-float")]
1052pub use optionals::ordered_float_impl;
1053#[cfg(feature = "ordered-float")]
1054pub use optionals::{OrderedFloat, ROrderedFloatOps};
1055
1056#[cfg(feature = "num-complex")]
1057pub use optionals::num_complex_impl;
1058#[cfg(feature = "num-complex")]
1059pub use optionals::{Complex, RComplexOps};
1060
1061#[cfg(feature = "num-traits")]
1062pub use optionals::num_traits_impl;
1063#[cfg(feature = "num-traits")]
1064pub use optionals::{RFloat, RNum, RSigned};
1065
1066#[cfg(feature = "uuid")]
1067pub use optionals::uuid_impl;
1068#[cfg(feature = "uuid")]
1069pub use optionals::{RUuidOps, Uuid, uuid_helpers};
1070
1071#[cfg(feature = "regex")]
1072pub use optionals::regex_impl;
1073#[cfg(feature = "regex")]
1074pub use optionals::{CaptureGroups, RCaptureGroups, RRegexOps, Regex};
1075
1076#[cfg(feature = "url")]
1077pub use optionals::url_impl;
1078#[cfg(feature = "url")]
1079pub use optionals::{RUrlOps, Url, url_helpers};
1080
1081#[cfg(feature = "aho-corasick")]
1082pub use optionals::aho_corasick_impl;
1083#[cfg(feature = "aho-corasick")]
1084pub use optionals::{
1085 AhoCorasick, RAhoCorasickOps, aho_compile, aho_count_matches, aho_find_all, aho_find_all_flat,
1086 aho_find_first, aho_is_match, aho_replace_all,
1087};
1088
1089#[cfg(feature = "indexmap")]
1090pub use optionals::indexmap_impl;
1091#[cfg(feature = "indexmap")]
1092pub use optionals::{IndexMap, RIndexMapOps};
1093
1094#[cfg(feature = "time")]
1095pub use optionals::time_impl;
1096#[cfg(feature = "time")]
1097pub use optionals::{Date, Duration, OffsetDateTime, RDateTimeFormat, RDuration};
1098#[cfg(feature = "time")]
1099pub use time;
1100
1101#[cfg(feature = "jiff")]
1102pub use jiff;
1103#[cfg(feature = "jiff")]
1104pub use optionals::jiff_impl;
1105#[cfg(feature = "jiff")]
1106pub use optionals::{
1107 JiffDate, JiffDateTime, JiffTime, JiffTimestampVec, JiffZonedVec, RDate, RDateTime,
1108 RSignedDuration, RSpan, RTime, RTimestamp, RZoned, SignedDuration, Span, Timestamp, Zoned,
1109};
1110
1111#[cfg(feature = "serde_json")]
1112pub use optionals::serde_impl;
1113#[cfg(feature = "toml")]
1114pub use optionals::toml_impl;
1115#[cfg(feature = "serde_json")]
1116pub use optionals::{
1117 FactorHandling, JsonOptions, JsonValue, NaHandling, RDeserialize, RJsonBridge, RJsonValueOps,
1118 RSerialize, SpecialFloatHandling, json_from_sexp, json_from_sexp_permissive,
1119 json_from_sexp_strict, json_from_sexp_with, json_into_sexp,
1120};
1121#[cfg(feature = "toml")]
1122pub use optionals::{RTomlOps, TomlValue, toml_from_str, toml_to_string, toml_to_string_pretty};
1123
1124#[cfg(feature = "bytes")]
1125pub use optionals::bytes_impl;
1126#[cfg(feature = "bytes")]
1127pub use optionals::{Buf, BufMut, Bytes, BytesMut, RBuf, RBufMut};
1128
1129#[cfg(feature = "sha2")]
1130pub use optionals::sha2_impl;
1131#[cfg(feature = "sha2")]
1132pub use optionals::{sha256_bytes, sha256_str, sha512_bytes, sha512_str};
1133
1134#[cfg(feature = "blake3")]
1135pub use optionals::blake3_impl;
1136#[cfg(feature = "blake3")]
1137pub use optionals::{blake3_bytes, blake3_hex, blake3_str};
1138
1139#[cfg(feature = "md5")]
1140pub use optionals::md5_impl;
1141#[cfg(feature = "md5")]
1142pub use optionals::{md5_bytes, md5_hex, md5_str};
1143
1144#[cfg(feature = "globset")]
1145pub use optionals::globset_impl;
1146#[cfg(feature = "globset")]
1147pub use optionals::{
1148 Glob, GlobBuilder, GlobOptions, GlobSet, GlobSetBuilder, build_globset, globset_is_match,
1149 globset_matches,
1150};
1151
1152#[cfg(feature = "zstd")]
1153pub use optionals::zstd_impl;
1154#[cfg(feature = "zstd")]
1155pub use optionals::{zstd_compress, zstd_decompress};
1156
1157#[cfg(feature = "borsh")]
1158pub use optionals::borsh_impl;
1159#[cfg(feature = "borsh")]
1160pub use optionals::{Borsh, RBorshOps, borsh_from_raw, borsh_to_raw};
1161
1162#[cfg(feature = "bitflags")]
1163pub use bitflags;
1164#[cfg(feature = "bitflags")]
1165pub use optionals::bitflags_impl;
1166#[cfg(feature = "bitflags")]
1167pub use optionals::{Flags, RFlags};
1168
1169#[cfg(feature = "bitvec")]
1170pub use optionals::bitvec_impl;
1171#[cfg(feature = "bitvec")]
1172pub use optionals::{BitVec, Lsb0, Msb0, RBitVec};
1173
1174#[cfg(feature = "tabled")]
1175pub use optionals::tabled_impl;
1176#[cfg(feature = "tabled")]
1177pub use optionals::{
1178 Builder, Table, Tabled, builder_to_string, table_from_vecs, table_to_string,
1179 table_to_string_opts, table_to_string_styled,
1180};
1181
1182#[cfg(feature = "tinyvec")]
1183pub use optionals::tinyvec_impl;
1184#[cfg(feature = "tinyvec")]
1185pub use optionals::{Array, ArrayVec, TinyVec};
1186
1187#[cfg(feature = "arrow")]
1188pub use optionals::arrow_impl;
1189#[cfg(feature = "arrow")]
1190pub use optionals::{
1191 ArrayRef, ArrowArray, BooleanArray, DataType, Date32Array, DictionaryArray, Field,
1192 Float64Array, Int32Array, RecordBatch, Schema, StringArray, StringDictionaryArray,
1193 TimestampSecondArray, UInt8Array,
1194};
1195
1196#[cfg(feature = "datafusion")]
1197pub use optionals::RSessionContext;
1198#[cfg(feature = "datafusion")]
1199pub use optionals::datafusion_impl;
1200
1201/// N-dimensional R arrays with const generic dimension count.
1202pub mod rarray;
1203pub use rarray::{RArray, RArray3D, RMatrix, RVector};
1204
1205/// Direct R serialization via serde (no JSON intermediate).
1206///
1207/// Provides efficient type-preserving conversions between Rust types and native R objects:
1208/// - [`AsSerialize<T>`][serde::AsSerialize] - Wrapper for returning `Serialize` types from `#[miniextendr]` functions
1209/// - [`RSerializeNative`][serde::RSerializeNative] - Convert Rust → R (struct → named list)
1210/// - [`RDeserializeNative`][serde::RDeserializeNative] - Convert R → Rust (named list → struct)
1211///
1212/// Enable with `features = ["serde"]`.
1213///
1214/// See the [`serde`] module documentation for type mappings and examples.
1215#[cfg(feature = "serde")]
1216pub mod serde;
1217/// Re-export the upstream `serde` crate (aliased to avoid conflict with [`mod serde`]).
1218///
1219/// Downstream crates can use `miniextendr_api::serde_crate::{Serialize, Deserialize}`
1220/// and `#[serde(crate = "miniextendr_api::serde_crate")]` to avoid a direct `serde` dep.
1221#[cfg(feature = "serde")]
1222pub use ::serde as serde_crate;
1223
1224/// Integration with the `bytemuck` crate for POD type conversions.
1225///
1226/// Provides explicit, safe conversions between Rust POD (Plain Old Data) types
1227/// and R raw vectors:
1228/// - `Raw<T>` - Single POD value (headerless, native layout)
1229/// - `RawSlice<T>` - Sequence of POD values (headerless)
1230/// - `RawTagged<T>` / `RawSliceTagged<T>` - With header metadata
1231///
1232/// Enable with `features = ["raw_conversions"]`.
1233///
1234/// ```ignore
1235/// use bytemuck::{Pod, Zeroable};
1236/// use miniextendr_api::raw_conversions::{Raw, RawSlice};
1237///
1238/// #[derive(Copy, Clone, Pod, Zeroable)]
1239/// #[repr(C)]
1240/// struct Vec3 { x: f32, y: f32, z: f32 }
1241///
1242/// #[miniextendr]
1243/// fn encode(x: f64, y: f64, z: f64) -> Raw<Vec3> {
1244/// Raw(Vec3 { x: x as f32, y: y as f32, z: z as f32 })
1245/// }
1246/// ```
1247#[cfg(feature = "raw_conversions")]
1248pub mod raw_conversions;
1249#[cfg(feature = "raw_conversions")]
1250pub use raw_conversions::{
1251 Pod, Raw, RawError, RawHeader, RawSlice, RawSliceTagged, RawTagged, Zeroable, raw_from_bytes,
1252 raw_slice_from_bytes, raw_slice_to_bytes, raw_to_bytes,
1253};
1254
1255/// `match.arg`-style string conversion for enums.
1256///
1257/// Provides the [`MatchArg`] trait for converting Rust enums to/from R character
1258/// strings with partial matching, like R's `match.arg()`.
1259/// Use `#[derive(MatchArg)]` on C-style enums to auto-generate the implementation.
1260pub mod match_arg;
1261#[cfg(feature = "either")]
1262pub use match_arg::match_arg_either_or;
1263pub use match_arg::{
1264 MatchArg, MatchArgAlias, MatchArgError, choices_sexp, match_arg_from_sexp,
1265 match_arg_missing_or, match_arg_null_or, match_arg_option_from_sexp, match_arg_param,
1266 match_arg_param_with_default, match_arg_vec_from_sexp, match_arg_vec_into_sexp,
1267};
1268
1269/// Factor support for enum ↔ R factor conversions.
1270///
1271/// Provides the [`RFactor`] trait for converting Rust enums to/from R factors.
1272/// Use `#[derive(RFactor)]` on C-style enums to auto-generate the implementation.
1273///
1274/// # Example
1275///
1276/// ```ignore
1277/// use miniextendr_api::RFactor;
1278///
1279/// #[derive(Copy, Clone, RFactor)]
1280/// enum Color { Red, Green, Blue }
1281///
1282/// #[miniextendr]
1283/// fn color_name(c: Color) -> &'static str {
1284/// match c {
1285/// Color::Red => "red",
1286/// Color::Green => "green",
1287/// Color::Blue => "blue",
1288/// }
1289/// }
1290/// ```
1291pub mod factor;
1292pub use factor::{
1293 FactorOptionVec, FactorVec, RFactor, UnitEnumFactor, build_factor, build_levels_sexp,
1294 build_levels_sexp_cached, factor_from_sexp,
1295};
1296
1297/// Convenience re-exports for common miniextendr items.
1298///
1299/// A single `use miniextendr_api::prelude::*;` brings into scope the most
1300/// commonly used macros, traits, types, and helpers.
1301pub mod prelude;
1302// endregion