miniextendr_api/
prelude.rs

1//! Convenience re-exports for common miniextendr items.
2//!
3//! A single `use miniextendr_api::prelude::*;` brings into scope the most
4//! commonly used macros, traits, types, and helpers so user crates can avoid
5//! a long list of individual imports.
6//!
7//! ## Optional feature types
8//!
9//! When a Cargo feature is enabled (e.g., `uuid`, `regex`, `ndarray`), the
10//! prelude includes both the miniextendr adapter types **and** a re-export of
11//! the upstream dependency crate itself. This means you do **not** need to add
12//! optional crates as direct dependencies in your `Cargo.toml` — enabling the
13//! feature on `miniextendr-api` is enough.
14//!
15//! ```toml
16//! [dependencies]
17//! miniextendr-api = { version = "0.1", features = ["uuid", "ndarray"] }
18//! # No need for: uuid = "1", ndarray = "0.16"
19//! ```
20//!
21//! Access the upstream crate via the prelude:
22//!
23//! ```ignore
24//! use miniextendr_api::prelude::*;
25//!
26//! // Uuid is re-exported from the uuid crate
27//! let id = Uuid::new_v4();
28//!
29//! // The full crate is also available for advanced usage
30//! let parsed = uuid::Uuid::parse_str("...").unwrap();
31//! ```
32//!
33//! # Example
34//!
35//! ```ignore
36//! use miniextendr_api::prelude::*;
37//!
38//! #[miniextendr]
39//! fn add(a: i32, b: i32) -> i32 {
40//!     a + b
41//! }
42//! ```
43
44// region: Proc-macro re-exports
45pub use crate::{
46    // Derive macros
47    AllEqual,
48    Altrep,
49    AltrepComplex,
50    AltrepInteger,
51    AltrepList,
52    AltrepLogical,
53    AltrepRaw,
54    AltrepReal,
55    AltrepString,
56    ExternalPtr,
57    MatchArg,
58    RFactor,
59    list,
60    miniextendr,
61    reexport,
62    typed_dataframe,
63    typed_list,
64};
65// endregion
66
67// region: Core traits
68pub use crate::altrep::RegisterAltrep;
69// Round out the ALTREP surface so it matches the DataFrame/serde prelude precedent.
70pub use crate::{
71    AltComplexData, AltIntegerData, AltListData, AltLogicalData, AltRawData, AltRealData,
72    AltStringData, AltrepExtract, AltrepLen, Coerce, IntoR, IntoRAltrep, TryCoerce, TryFromRoot,
73    TryFromSexp,
74};
75// endregion
76
77// region: Types
78pub use crate::{
79    BuiltList, Call, CallerCall, Checked, ExternalPtrMut, ExternalPtrRef, IntoList, Invisible,
80    Lazy, LazyDots, List, ListBuilder, ListMut, Missing, NArgs, NamedListBuilder, NamedVector,
81    Nullable, OwnedProtect, Preserved, ProtectPool, ProtectScope, Protected, ProtectedStrVec,
82    Quosure, Quoted, RCow, StrVec, StrVecBuilder, Unchecked, Visible,
83};
84// endregion
85
86// region: DataFrame family
87//
88// The row/group-level data-frame surface: the owned type, its error, the
89// conversion trait pair, and the `#[derive(DataFrameRow)]` macro. Group-level
90// items (`GroupedDataFrame`, `GroupKey`, `RealKey`, `GroupDeclaration`,
91// `group_rows`) stay at the crate root
92// — `df.group_by(..)` returns them without the caller naming the types.
93pub use crate::{
94    BuiltDataFrame, ColumnarFrame, DataFrame, DataFrameError, DataFrameRow, DataFrameShape,
95    FromDataFrame, IntoDataFrame, IntoDataFrameSplit,
96};
97// endregion
98
99// region: Extension-trait `.wrap_*()` verbs
100//
101// The `As*Ext` family is blanket-impl'd over the `Into*` traits and provides the
102// method-style return verbs (`value.wrap_data_frame()`, `.wrap_list()`,
103// `.wrap_external_ptr()`, …) that a `#[derive(DataFrameRow)]` / `#[derive(List)]`
104// / … type gets for free. They were already re-exported at the crate root but
105// not from the prelude, leaving `IntoDataFrame` / `FromDataFrame` (above) exposed
106// while their `.wrap_*()` companions were not — this closes that gap so the
107// canonical surface is fully discoverable via `use miniextendr_api::prelude::*`.
108#[cfg(feature = "vctrs")]
109pub use crate::AsVctrsExt;
110pub use crate::{
111    AsDataFrameExt, AsExternalPtrExt, AsListExt, AsNamedListExt, AsNamedVectorExt, AsRNativeExt,
112};
113// endregion
114
115// region: Worker thread
116pub use crate::{Sendable, with_r_thread};
117// endregion
118
119// region: Error handling and console output
120pub use crate::{r_print, r_println, r_warning};
121// endregion
122
123// region: R evaluation
124//
125// `r!` / `r_str!` evaluate R source from Rust; `r_eval_str` is the underlying
126// protect-safe parse + eval function they expand to, and `REvalError` the R
127// error they return.
128pub use crate::expression::{REvalError, r_eval_str};
129pub use crate::{r, r_str};
130// endregion
131
132// region: Safe R-value surface
133//
134// `SEXP` is the central newtype; `SexpExt` is the ergonomic extension trait
135// that provides the safe higher-level methods, `PairListExt` the pairlist
136// (call) accessors. The type vocabulary
137// (`SEXPTYPE`, `R_xlen_t`, `RLogical`, `Rboolean`, `Rcomplex`, `RNativeType`,
138// …) is **not** re-exported here — those are lower-level types that user
139// code should reach for explicitly at the crate root
140// (`miniextendr_api::SEXPTYPE`, `miniextendr_api::R_xlen_t`, …) when
141// genuinely needed (rare; common in tests and macro-generated code).
142// `miniextendr_api::sys::*` is the raw-FFI escape hatch — `extern
143// "C-unwind"` symbols and the ALTREP method type aliases only. The prelude
144// is for the abstraction surface, not the raw R C API.
145pub use crate::{PairListExt, SEXP, SexpExt};
146// endregion
147
148// region: Optional feature re-exports
149
150// --- either ---
151#[cfg(feature = "either")]
152pub use crate::{Either, Left, Right};
153
154#[cfg(feature = "either")]
155pub use either;
156
157// --- uuid ---
158#[cfg(feature = "uuid")]
159pub use crate::{RUuidOps, Uuid};
160#[cfg(feature = "uuid")]
161pub use uuid;
162
163// --- regex ---
164#[cfg(feature = "regex")]
165pub use crate::{CaptureGroups, RRegexOps, Regex};
166#[cfg(feature = "regex")]
167pub use regex;
168
169// --- url ---
170#[cfg(feature = "url")]
171pub use crate::{RUrlOps, Url};
172#[cfg(feature = "url")]
173pub use url;
174
175// --- time ---
176#[cfg(feature = "time")]
177pub use crate::{Date, Duration, OffsetDateTime, RDuration};
178#[cfg(feature = "time")]
179pub use time;
180
181// --- ordered-float ---
182#[cfg(feature = "ordered-float")]
183pub use crate::{OrderedFloat, ROrderedFloatOps};
184#[cfg(feature = "ordered-float")]
185pub use ordered_float;
186
187// --- num-bigint ---
188#[cfg(feature = "num-bigint")]
189pub use crate::{BigInt, BigUint, RBigIntOps, RBigUintOps};
190#[cfg(feature = "num-bigint")]
191pub use num_bigint;
192
193// --- rust_decimal ---
194#[cfg(feature = "rust_decimal")]
195pub use crate::{Decimal, RDecimalOps};
196#[cfg(feature = "rust_decimal")]
197pub use rust_decimal;
198
199// --- num-complex ---
200#[cfg(feature = "num-complex")]
201pub use crate::{Complex, RComplexOps};
202#[cfg(feature = "num-complex")]
203pub use num_complex;
204
205// --- num-traits ---
206#[cfg(feature = "num-traits")]
207pub use crate::{RFloat, RNum, RSigned};
208#[cfg(feature = "num-traits")]
209pub use num_traits;
210
211// --- ndarray ---
212#[cfg(feature = "ndarray")]
213pub use crate::{
214    Array1, Array2, Array3, Array4, Array5, Array6, ArrayD, ArrayView1, ArrayView2, ArrayViewD,
215    ArrayViewMut1, ArrayViewMut2, ArrayViewMutD, RNdArrayOps,
216};
217#[cfg(feature = "ndarray")]
218pub use ndarray;
219
220// --- nalgebra ---
221#[cfg(feature = "nalgebra")]
222pub use crate::{DMatrix, DVector, RMatrixOps, RVectorOps, SMatrix, SVector};
223#[cfg(feature = "nalgebra")]
224pub use nalgebra;
225
226// --- indexmap ---
227#[cfg(feature = "indexmap")]
228pub use crate::{IndexMap, RIndexMapOps};
229#[cfg(feature = "indexmap")]
230pub use indexmap;
231
232// --- rayon ---
233#[cfg(feature = "rayon")]
234pub use crate::{RParallelExtend, RParallelIterator};
235#[cfg(feature = "rayon")]
236pub use rayon;
237
238// --- rand ---
239#[cfg(feature = "rand")]
240pub use crate::{RDistributionOps, RDistributions, RRng, RRngOps};
241#[cfg(feature = "rand")]
242pub use rand;
243#[cfg(feature = "rand_distr")]
244pub use rand_distr;
245
246// --- serde (direct R serialization) ---
247#[cfg(feature = "serde")]
248pub use crate::serde::{AsSerialize, RDeserializeNative, RSerializeNative, SerdeErrorShape};
249// Unconditional: without `serde` the macro is a compile error saying so.
250pub use crate::serde_error_shape;
251#[cfg(feature = "serde")]
252pub use serde;
253
254// --- serde_json ---
255#[cfg(feature = "serde_json")]
256pub use crate::{JsonOptions, JsonValue, RDeserialize, RSerialize};
257#[cfg(feature = "serde_json")]
258pub use serde_json;
259
260// --- toml ---
261#[cfg(feature = "toml")]
262pub use crate::{TomlValue, toml_from_str, toml_to_string};
263#[cfg(feature = "toml")]
264pub use toml;
265
266// --- bytes ---
267#[cfg(feature = "bytes")]
268pub use crate::{Bytes, BytesMut, RBuf, RBufMut};
269#[cfg(feature = "bytes")]
270pub use bytes;
271
272// --- aho-corasick ---
273#[cfg(feature = "aho-corasick")]
274pub use crate::{AhoCorasick, aho_compile};
275#[cfg(feature = "aho-corasick")]
276pub use aho_corasick;
277
278// --- bitflags ---
279#[cfg(feature = "bitflags")]
280pub use crate::RFlags;
281#[cfg(feature = "bitflags")]
282pub use bitflags;
283
284// --- bitvec ---
285#[cfg(feature = "bitvec")]
286pub use crate::RBitVec;
287#[cfg(feature = "bitvec")]
288pub use bitvec;
289
290// --- borsh ---
291#[cfg(feature = "borsh")]
292pub use crate::{Borsh, RBorshOps};
293#[cfg(feature = "borsh")]
294pub use borsh;
295
296// --- raw_conversions ---
297#[cfg(feature = "raw_conversions")]
298pub use crate::{Pod, Raw, RawSlice, Zeroable};
299#[cfg(feature = "raw_conversions")]
300pub use bytemuck;
301
302// --- sha2 ---
303#[cfg(feature = "sha2")]
304pub use crate::{sha256_bytes, sha256_str, sha512_bytes, sha512_str};
305#[cfg(feature = "sha2")]
306pub use sha2;
307
308// --- tabled ---
309#[cfg(feature = "tabled")]
310pub use crate::{Table, Tabled, table_to_string};
311#[cfg(feature = "tabled")]
312pub use tabled;
313
314// --- tinyvec ---
315#[cfg(feature = "tinyvec")]
316pub use crate::{ArrayVec, TinyVec};
317#[cfg(feature = "tinyvec")]
318pub use tinyvec;
319
320// --- indicatif ---
321#[cfg(feature = "indicatif")]
322pub use crate::progress;
323#[cfg(feature = "indicatif")]
324pub use indicatif;
325
326// --- vctrs ---
327#[cfg(feature = "vctrs")]
328pub use crate::{IntoVctrs, VctrsClass};
329// endregion
330
331// Explicit class-system return markers.
332pub use crate::wrap_as::{
333    ConvertFrom, ConvertTo, WrapAsEnv, WrapAsR6, WrapAsS3, WrapAsS4, WrapAsS7, WrapAsVctrs,
334};
miniextendr_api/prelude.rs

miniextendr_api/
prelude.rs
