qubit_function/lib.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! # Qubit Function
11//!
12//! Provides functional programming abstractions for Rust, including:
13//!
14//! - **Function types**: Compute results from borrowed values
15//! - **MutatingFunction types**: Mutate borrowed values and return results
16//! - **BiFunction types**: Compute results from two borrowed values
17//! - **BiMutatingFunction types**: Mutate two borrowed values and return results
18//! - **Transformer types**: Transform values from type T to type R
19//! - **UnaryOperator types**: Transform values of type T to the same type T
20//! - **BiTransformer types**: Transform two values to produce a result
21//! - **BinaryOperator types**: Transform two values of type T to produce a T
22//! - **StatefulBinaryOperator types**: Stateful transform two values of type T to produce a T
23//! - **Consumer types**: Functions that consume values without returning
24//! - **BiConsumer types**: Functions that consume two values without returning
25//! - **Predicate types**: Functions that test values and return boolean
26//! - **BiPredicate types**: Functions that test two values and return boolean
27//! - **Supplier types**: Functions that produce values without input
28//! - **Mutator types**: Functions that mutate values in place
29//! - **Task types**: Fallible zero-argument and mutable-input actions and computations
30//! - **Tester types**: Functions that test conditions without input
31//! - **Comparator types**: Functions that compare values and return ordering
32//!
33
34// Module declarations
35pub mod comparator;
36pub mod consumers;
37pub mod functions;
38#[doc(hidden)]
39pub mod macros;
40pub mod mutators;
41pub mod predicates;
42pub mod suppliers;
43pub mod tasks;
44pub mod tester;
45pub mod transformers;
46
47// Re-export common types from module roots for ergonomic crate-level imports.
48// Types are organized by functionality and ownership model for better readability.
49
50// =============================================================================
51// Core Functional Types
52// =============================================================================
53
54// ---- Consumer Types (Fn(&T)) ----
55pub use consumers::{
56 // Arc-based (shared multi-threaded ownership)
57 ArcConditionalConsumer,
58 ArcConditionalStatefulConsumer,
59 ArcConsumer,
60 ArcStatefulConsumer,
61
62 // Box-based (single ownership)
63 BoxConditionalConsumer,
64 BoxConditionalConsumerOnce,
65 BoxConditionalStatefulConsumer,
66 BoxConsumer,
67 BoxConsumerOnce,
68 BoxStatefulConsumer,
69
70 // Core traits
71 Consumer,
72 ConsumerOnce,
73 FnConsumerOnceOps,
74 // Extension traits
75 FnConsumerOps,
76 FnStatefulConsumerOps,
77 // Rc-based (shared single-threaded ownership)
78 RcConditionalConsumer,
79 RcConditionalStatefulConsumer,
80 RcConsumer,
81 RcStatefulConsumer,
82
83 StatefulConsumer,
84};
85
86// ---- BiConsumer Types (Fn(&T, &U)) ----
87pub use consumers::{
88 // Arc-based (shared multi-threaded ownership)
89 ArcBiConsumer,
90 ArcConditionalBiConsumer,
91 ArcConditionalStatefulBiConsumer,
92 ArcStatefulBiConsumer,
93
94 // Core traits
95 BiConsumer,
96 BiConsumerOnce,
97 // Box-based (single ownership)
98 BoxBiConsumer,
99 BoxBiConsumerOnce,
100 BoxConditionalBiConsumer,
101 BoxConditionalBiConsumerOnce,
102 BoxConditionalStatefulBiConsumer,
103 BoxStatefulBiConsumer,
104
105 FnBiConsumerOnceOps,
106 // Extension traits
107 FnBiConsumerOps,
108 FnStatefulBiConsumerOps,
109 // Rc-based (shared single-threaded ownership)
110 RcBiConsumer,
111 RcConditionalBiConsumer,
112 RcConditionalStatefulBiConsumer,
113 RcStatefulBiConsumer,
114
115 StatefulBiConsumer,
116};
117
118// ---- Function Types (Fn(&T) -> R) ----
119pub use functions::{
120 // Arc-based (shared multi-threaded ownership)
121 ArcFunction,
122 ArcMutatingFunction,
123 ArcStatefulFunction,
124 ArcStatefulMutatingFunction,
125
126 // Box-based (single ownership)
127 BoxFunction,
128 BoxFunctionOnce,
129 BoxMutatingFunction,
130 BoxMutatingFunctionOnce,
131 BoxStatefulFunction,
132 BoxStatefulMutatingFunction,
133
134 FnFunctionOnceOps,
135 // Extension traits
136 FnFunctionOps,
137 FnMutatingFunctionOnceOps,
138 FnMutatingFunctionOps,
139 FnStatefulFunctionOps,
140 FnStatefulMutatingFunctionOps,
141 // Core traits
142 Function,
143 FunctionOnce,
144 MutatingFunction,
145 MutatingFunctionOnce,
146 // Rc-based (shared single-threaded ownership)
147 RcFunction,
148 RcMutatingFunction,
149 RcStatefulFunction,
150 RcStatefulMutatingFunction,
151
152 StatefulFunction,
153 StatefulMutatingFunction,
154};
155
156// ---- BiFunction Types (Fn(&T, &U) -> R) ----
157pub use functions::{
158 // Arc-based (shared multi-threaded ownership)
159 ArcBiFunction,
160 ArcBiMutatingFunction,
161
162 // Core traits
163 BiFunction,
164 BiFunctionOnce,
165 BiMutatingFunction,
166 BiMutatingFunctionOnce,
167
168 // Box-based (single ownership)
169 BoxBiFunction,
170 BoxBiFunctionOnce,
171 BoxBiMutatingFunction,
172 BoxBiMutatingFunctionOnce,
173
174 FnBiFunctionOnceOps,
175 // Extension traits
176 FnBiFunctionOps,
177 FnBiMutatingFunctionOnceOps,
178 FnBiMutatingFunctionOps,
179 // Rc-based (shared single-threaded ownership)
180 RcBiFunction,
181 RcBiMutatingFunction,
182};
183
184// ---- Binary Function Types (Fn(&T, &T) -> R) ----
185pub use functions::{
186 // Arc-based (shared multi-threaded ownership)
187 ArcBinaryFunction,
188 ArcBinaryMutatingFunction,
189 // Box-based (single ownership)
190 BoxBinaryFunction,
191 BoxBinaryMutatingFunction,
192
193 // Rc-based (shared single-threaded ownership)
194 RcBinaryFunction,
195 RcBinaryMutatingFunction,
196};
197
198// ---- Conditional Function Types ----
199pub use functions::{
200 ArcConditionalBiFunction,
201 ArcConditionalBiMutatingFunction,
202 // Arc-based (shared multi-threaded ownership)
203 ArcConditionalFunction,
204 ArcConditionalMutatingFunction,
205 ArcConditionalStatefulFunction,
206 ArcConditionalStatefulMutatingFunction,
207 BoxConditionalBiFunction,
208 BoxConditionalBiFunctionOnce,
209 BoxConditionalBiMutatingFunction,
210 BoxConditionalBiMutatingFunctionOnce,
211 // Box-based (single ownership)
212 BoxConditionalFunction,
213 BoxConditionalFunctionOnce,
214 BoxConditionalMutatingFunction,
215 BoxConditionalMutatingFunctionOnce,
216
217 BoxConditionalStatefulFunction,
218 BoxConditionalStatefulMutatingFunction,
219 RcConditionalBiFunction,
220 RcConditionalBiMutatingFunction,
221 // Rc-based (shared single-threaded ownership)
222 RcConditionalFunction,
223 RcConditionalMutatingFunction,
224
225 RcConditionalStatefulFunction,
226 RcConditionalStatefulMutatingFunction,
227};
228
229// =============================================================================
230// Data Processing Types
231// =============================================================================
232
233// ---- Transformer Types (Fn(T) -> R) ----
234pub use transformers::{
235 ArcStatefulBiTransformer,
236
237 ArcStatefulTransformer,
238 // Arc-based (shared multi-threaded ownership)
239 ArcTransformer,
240 BoxStatefulBiTransformer,
241
242 BoxStatefulTransformer,
243 // Box-based (single ownership)
244 BoxTransformer,
245 BoxTransformerOnce,
246 FnStatefulBiTransformerOps,
247 FnStatefulTransformerOps,
248 FnTransformerOnceOps,
249 // Extension traits
250 FnTransformerOps,
251 RcStatefulBiTransformer,
252
253 RcStatefulTransformer,
254 // Rc-based (shared single-threaded ownership)
255 RcTransformer,
256 StatefulBiTransformer,
257
258 StatefulTransformer,
259 // Core traits
260 Transformer,
261 TransformerOnce,
262};
263
264// ---- BiTransformer Types (Fn(T, U) -> R) ----
265pub use transformers::{
266 // Arc-based (shared multi-threaded ownership)
267 ArcBiTransformer,
268
269 // Core traits
270 BiTransformer,
271 BiTransformerOnce,
272
273 // Box-based (single ownership)
274 BoxBiTransformer,
275 BoxBiTransformerOnce,
276
277 FnBiTransformerOnceOps,
278 // Extension traits
279 FnBiTransformerOps,
280 // Rc-based (shared single-threaded ownership)
281 RcBiTransformer,
282};
283
284// ---- Operator Types ----
285// Binary operators (Fn(T, T) -> T)
286pub use transformers::{
287 ArcBinaryOperator,
288 BinaryOperator,
289 BinaryOperatorOnce,
290 BoxBinaryOperator,
291 BoxBinaryOperatorOnce,
292 RcBinaryOperator,
293};
294
295// Stateful binary operators (FnMut(T, T) -> T)
296pub use transformers::{
297 ArcStatefulBinaryOperator,
298 BoxStatefulBinaryOperator,
299 RcStatefulBinaryOperator,
300 StatefulBinaryOperator,
301};
302
303// Unary operators (Fn(T) -> T)
304pub use transformers::{
305 ArcUnaryOperator,
306 BoxUnaryOperator,
307 BoxUnaryOperatorOnce,
308 RcUnaryOperator,
309 UnaryOperator,
310 UnaryOperatorOnce,
311};
312
313// ---- Conditional Transformer Types ----
314pub use transformers::{
315 ArcConditionalBiTransformer,
316 ArcConditionalStatefulBiTransformer,
317 ArcConditionalStatefulTransformer,
318 // Arc-based (shared multi-threaded ownership)
319 ArcConditionalTransformer,
320 BoxConditionalBiTransformer,
321 BoxConditionalBiTransformerOnce,
322 BoxConditionalStatefulBiTransformer,
323
324 BoxConditionalStatefulTransformer,
325 // Box-based (single ownership)
326 BoxConditionalTransformer,
327 BoxConditionalTransformerOnce,
328 RcConditionalBiTransformer,
329 RcConditionalStatefulBiTransformer,
330
331 RcConditionalStatefulTransformer,
332 // Rc-based (shared single-threaded ownership)
333 RcConditionalTransformer,
334};
335
336// =============================================================================
337// Utility Types
338// =============================================================================
339
340// ---- Mutator Types (Fn(&mut T)) ----
341pub use mutators::{
342 ArcConditionalMutator,
343 ArcConditionalStatefulMutator,
344
345 // Arc-based (shared multi-threaded ownership)
346 ArcMutator,
347 ArcStatefulMutator,
348
349 // Conditional types
350 BoxConditionalMutator,
351 BoxConditionalMutatorOnce,
352 BoxConditionalStatefulMutator,
353 // Box-based (single ownership)
354 BoxMutator,
355 BoxMutatorOnce,
356 BoxStatefulMutator,
357
358 FnMutStatefulMutatorOps,
359 FnMutatorOnceOps,
360 // Extension traits
361 FnMutatorOps,
362 // Core traits
363 Mutator,
364 MutatorOnce,
365 RcConditionalMutator,
366 RcConditionalStatefulMutator,
367 // Rc-based (shared single-threaded ownership)
368 RcMutator,
369 RcStatefulMutator,
370
371 StatefulMutator,
372};
373
374// ---- Predicate Types (Fn(&T) -> bool) ----
375pub use predicates::{
376 // Arc-based (shared multi-threaded ownership)
377 ArcPredicate,
378
379 // Box-based (single ownership)
380 BoxPredicate,
381
382 // Extension traits
383 FnPredicateOps,
384 // Core traits
385 Predicate,
386
387 // Rc-based (shared single-threaded ownership)
388 RcPredicate,
389};
390
391// ---- BiPredicate Types (Fn(&T, &U) -> bool) ----
392pub use predicates::{
393 // Arc-based (shared multi-threaded ownership)
394 ArcBiPredicate,
395
396 // Core traits
397 BiPredicate,
398
399 // Box-based (single ownership)
400 BoxBiPredicate,
401
402 // Extension traits
403 FnBiPredicateOps,
404 // Rc-based (shared single-threaded ownership)
405 RcBiPredicate,
406};
407
408// ---- Supplier Types (Fn() -> R) ----
409pub use suppliers::{
410 ArcStatefulSupplier,
411
412 // Arc-based (shared multi-threaded ownership)
413 ArcSupplier,
414 BoxStatefulSupplier,
415
416 // Box-based (single ownership)
417 BoxSupplier,
418 BoxSupplierOnce,
419 // Extension traits
420 FnStatefulSupplierOps,
421 RcStatefulSupplier,
422
423 // Rc-based (shared single-threaded ownership)
424 RcSupplier,
425 StatefulSupplier,
426
427 // Core traits
428 Supplier,
429 SupplierOnce,
430};
431
432// ---- Task Types (fallible actions and computations) ----
433pub use tasks::{
434 ArcCallable,
435 ArcCallableWith,
436 ArcRunnable,
437 ArcRunnableWith,
438 BoxCallable,
439 BoxCallableOnce,
440 BoxCallableWith,
441 BoxRunnable,
442 BoxRunnableOnce,
443 BoxRunnableWith,
444 Callable,
445 CallableOnce,
446 CallableWith,
447 RcCallable,
448 RcCallableWith,
449 RcRunnable,
450 RcRunnableWith,
451 Runnable,
452 RunnableOnce,
453 RunnableWith,
454};
455
456// ---- Comparator Types (Fn(&T, &T) -> Ordering) ----
457pub use comparator::{
458 // Arc-based (shared multi-threaded ownership)
459 ArcComparator,
460
461 // Box-based (single ownership)
462 BoxComparator,
463
464 // Core traits
465 Comparator,
466
467 // Extension traits
468 FnComparatorOps,
469 // Rc-based (shared single-threaded ownership)
470 RcComparator,
471};
472
473// ---- Tester Types (FnMut() -> bool) ----
474pub use tester::{
475 // Arc-based (shared multi-threaded ownership)
476 ArcTester,
477
478 // Box-based (single ownership)
479 BoxTester,
480
481 // Extension traits
482 FnTesterOps,
483 // Rc-based (shared single-threaded ownership)
484 RcTester,
485
486 // Core traits
487 Tester,
488};