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