qubit_function/transformers/
bi_transformer_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! # BiTransformerOnce Types
10//!
11//! Provides Rust implementations of consuming bi-transformer traits similar to
12//! Rust's `FnOnce` trait, but with value-oriented semantics for functional
13//! programming patterns with two inputs.
14//!
15//! This module provides the `BiTransformerOnce<T, U, R>` trait and one-time use
16//! implementations:
17//!
18//! - [`BoxBiTransformerOnce`]: Single ownership, one-time use
19//!
20//! # Author
21//!
22//! Haixing Hu
23use crate::macros::{
24    impl_box_once_conversions,
25    impl_closure_once_trait,
26};
27use crate::predicates::bi_predicate::{
28    BiPredicate,
29    BoxBiPredicate,
30};
31use crate::transformers::{
32    macros::{
33        impl_box_conditional_transformer,
34        impl_box_transformer_methods,
35        impl_conditional_transformer_debug_display,
36        impl_transformer_common_methods,
37        impl_transformer_constant_method,
38        impl_transformer_debug_display,
39    },
40    transformer_once::TransformerOnce,
41};
42
43mod box_bi_transformer_once;
44pub use box_bi_transformer_once::BoxBiTransformerOnce;
45mod fn_bi_transformer_once_ops;
46pub use fn_bi_transformer_once_ops::FnBiTransformerOnceOps;
47mod binary_operator_once;
48pub use binary_operator_once::BinaryOperatorOnce;
49mod box_binary_operator_once;
50pub use box_binary_operator_once::BoxBinaryOperatorOnce;
51mod box_conditional_bi_transformer_once;
52pub use box_conditional_bi_transformer_once::BoxConditionalBiTransformerOnce;
53
54// ============================================================================
55// Core Trait
56// ============================================================================
57
58/// BiTransformerOnce trait - consuming bi-transformation that takes ownership
59///
60/// Defines the behavior of a consuming bi-transformer: converting two values of
61/// types `T` and `U` to a value of type `R` by taking ownership of self and
62/// both inputs. This trait is analogous to `FnOnce(T, U) -> R`.
63///
64/// # Type Parameters
65///
66/// * `T` - The type of the first input value (consumed)
67/// * `U` - The type of the second input value (consumed)
68/// * `R` - The type of the output value
69///
70/// # Author
71///
72/// Haixing Hu
73pub trait BiTransformerOnce<T, U, R> {
74    /// Transforms two input values, consuming self and both inputs
75    ///
76    /// # Parameters
77    ///
78    /// * `first` - The first input value (consumed)
79    /// * `second` - The second input value (consumed)
80    ///
81    /// # Returns
82    ///
83    /// The transformed output value
84    fn apply(self, first: T, second: U) -> R;
85
86    /// Converts to BoxBiTransformerOnce
87    ///
88    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
89    /// after calling this method.
90    ///
91    /// # Returns
92    ///
93    /// Returns `BoxBiTransformerOnce<T, U, R>`
94    fn into_box(self) -> BoxBiTransformerOnce<T, U, R>
95    where
96        Self: Sized + 'static,
97    {
98        BoxBiTransformerOnce::new(move |t: T, u: U| self.apply(t, u))
99    }
100
101    /// Converts bi-transformer to a closure
102    ///
103    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
104    /// after calling this method.
105    ///
106    /// # Returns
107    ///
108    /// Returns a closure that implements `FnOnce(T, U) -> R`
109    fn into_fn(self) -> impl FnOnce(T, U) -> R
110    where
111        Self: Sized + 'static,
112    {
113        move |t: T, u: U| self.apply(t, u)
114    }
115
116    /// Converts bi-transformer to a boxed function pointer
117    ///
118    /// **📌 Borrows `&self`**: The original bi-transformer remains usable
119    /// after calling this method.
120    ///
121    /// # Returns
122    ///
123    /// Returns a boxed function pointer that implements `FnOnce(T, U) -> R`
124    ///
125    /// # Examples
126    ///
127    /// ```rust
128    /// use qubit_function::BiTransformerOnce;
129    ///
130    /// let add = |x: i32, y: i32| x + y;
131    /// let func = add.to_fn();
132    /// assert_eq!(func(20, 22), 42);
133    /// ```
134    fn to_box(&self) -> BoxBiTransformerOnce<T, U, R>
135    where
136        Self: Clone + 'static,
137    {
138        self.clone().into_box()
139    }
140
141    /// Converts bi-transformer to a closure
142    ///
143    /// **📌 Borrows `&self`**: The original bi-transformer remains usable
144    /// after calling this method.
145    ///
146    /// # Returns
147    ///
148    /// Returns a closure that implements `FnOnce(T, U) -> R`
149    ///
150    /// # Examples
151    ///
152    /// ```rust
153    /// use qubit_function::BiTransformerOnce;
154    ///
155    /// let add = |x: i32, y: i32| x + y;
156    /// let func = add.to_fn();
157    /// assert_eq!(func(20, 22), 42);
158    /// ```
159    fn to_fn(&self) -> impl FnOnce(T, U) -> R
160    where
161        Self: Clone + 'static,
162    {
163        self.clone().into_fn()
164    }
165}
qubit_function/transformers/bi_transformer_once.rs

qubit_function/transformers/
bi_transformer_once.rs
