qubit_function/transformers/
stateful_bi_transformer.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//! # StatefulBiTransformer Types
11//!
12//! Provides Rust implementations of stateful bi-transformer traits for type
13//! conversion and value transformation with two inputs. StatefulBiTransformers
14//! consume two input values (taking ownership) and produce an output value.
15//!
16//! This module provides the `StatefulBiTransformer<T, U, R>` trait and three
17//! implementations:
18//!
19//! - [`BoxStatefulBiTransformer`]: Single ownership, not cloneable
20//! - [`ArcStatefulBiTransformer`]: Thread-safe shared ownership, cloneable
21//! - [`RcStatefulBiTransformer`]: Single-threaded shared ownership, cloneable
22//!
23use std::cell::RefCell;
24use std::rc::Rc;
25use std::sync::Arc;
26
27use parking_lot::Mutex;
28
29use crate::macros::{
30    impl_arc_conversions,
31    impl_closure_trait,
32    impl_rc_conversions,
33};
34use crate::predicates::bi_predicate::{
35    ArcBiPredicate,
36    BiPredicate,
37    BoxBiPredicate,
38    RcBiPredicate,
39};
40use crate::transformers::{
41    bi_transformer_once::BoxBiTransformerOnce,
42    macros::{
43        impl_box_conditional_transformer,
44        impl_box_transformer_methods,
45        impl_conditional_transformer_clone,
46        impl_conditional_transformer_debug_display,
47        impl_shared_conditional_transformer,
48        impl_shared_transformer_methods,
49        impl_transformer_clone,
50        impl_transformer_common_methods,
51        impl_transformer_constant_method,
52        impl_transformer_debug_display,
53    },
54    stateful_transformer::StatefulTransformer,
55};
56
57mod box_stateful_bi_transformer;
58pub use box_stateful_bi_transformer::BoxStatefulBiTransformer;
59mod rc_stateful_bi_transformer;
60pub use rc_stateful_bi_transformer::RcStatefulBiTransformer;
61mod arc_stateful_bi_transformer;
62pub use arc_stateful_bi_transformer::ArcStatefulBiTransformer;
63mod fn_stateful_bi_transformer_ops;
64pub use fn_stateful_bi_transformer_ops::FnStatefulBiTransformerOps;
65mod stateful_binary_operator;
66pub use stateful_binary_operator::StatefulBinaryOperator;
67mod box_stateful_binary_operator;
68pub use box_stateful_binary_operator::BoxStatefulBinaryOperator;
69mod arc_stateful_binary_operator;
70pub use arc_stateful_binary_operator::ArcStatefulBinaryOperator;
71mod rc_stateful_binary_operator;
72pub use rc_stateful_binary_operator::RcStatefulBinaryOperator;
73mod box_conditional_stateful_bi_transformer;
74pub use box_conditional_stateful_bi_transformer::BoxConditionalStatefulBiTransformer;
75mod rc_conditional_stateful_bi_transformer;
76pub use rc_conditional_stateful_bi_transformer::RcConditionalStatefulBiTransformer;
77mod arc_conditional_stateful_bi_transformer;
78pub use arc_conditional_stateful_bi_transformer::ArcConditionalStatefulBiTransformer;
79
80// ============================================================================
81// Core Trait
82// ============================================================================
83
84/// StatefulBiTransformer trait - transforms two values to produce a result
85///
86/// Defines the behavior of a bi-transformation: converting two values of types
87/// `T` and `U` to a value of type `R` by consuming the inputs. This is
88/// analogous to `Fn(T, U) -> R` in Rust's standard library.
89///
90/// # Type Parameters
91///
92/// * `T` - The type of the first input value (consumed)
93/// * `U` - The type of the second input value (consumed)
94/// * `R` - The type of the output value
95///
96pub trait StatefulBiTransformer<T, U, R> {
97    /// Transforms two input values to produce an output value
98    ///
99    /// # Parameters
100    ///
101    /// * `first` - The first input value to transform (consumed)
102    /// * `second` - The second input value to transform (consumed)
103    ///
104    /// # Returns
105    ///
106    /// The transformed output value
107    fn apply(&mut self, first: T, second: U) -> R;
108
109    /// Converts to BoxStatefulBiTransformer
110    ///
111    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
112    /// after calling this method.
113    ///
114    /// # Default Implementation
115    ///
116    /// The default implementation wraps `self` in a `Box` and creates a
117    /// `BoxStatefulBiTransformer`. Types can override this method to provide more
118    /// efficient conversions.
119    ///
120    /// # Returns
121    ///
122    /// Returns `BoxStatefulBiTransformer<T, U, R>`
123    fn into_box(self) -> BoxStatefulBiTransformer<T, U, R>
124    where
125        Self: Sized + 'static,
126    {
127        let mut trans = self;
128        BoxStatefulBiTransformer::new(move |x, y| trans.apply(x, y))
129    }
130
131    /// Converts to RcStatefulBiTransformer
132    ///
133    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
134    /// after calling this method.
135    ///
136    /// # Default Implementation
137    ///
138    /// The default implementation wraps `self` in an `Rc` and creates an
139    /// `RcStatefulBiTransformer`. Types can override this method to provide more
140    /// efficient conversions.
141    ///
142    /// # Returns
143    ///
144    /// Returns `RcStatefulBiTransformer<T, U, R>`
145    fn into_rc(self) -> RcStatefulBiTransformer<T, U, R>
146    where
147        Self: Sized + 'static,
148    {
149        let mut trans = self;
150        RcStatefulBiTransformer::new(move |x, y| trans.apply(x, y))
151    }
152
153    /// Converts to ArcStatefulBiTransformer
154    ///
155    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
156    /// after calling this method.
157    ///
158    /// # Default Implementation
159    ///
160    /// The default implementation wraps `self` in an `Arc` and creates an
161    /// `ArcStatefulBiTransformer`. Types can override this method to provide more
162    /// efficient conversions.
163    ///
164    /// # Returns
165    ///
166    /// Returns `ArcStatefulBiTransformer<T, U, R>`
167    fn into_arc(self) -> ArcStatefulBiTransformer<T, U, R>
168    where
169        Self: Sized + Send + 'static,
170    {
171        let mut trans = self;
172        ArcStatefulBiTransformer::new(move |x, y| trans.apply(x, y))
173    }
174
175    /// Converts bi-transformer to a closure
176    ///
177    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
178    /// after calling this method.
179    ///
180    /// # Default Implementation
181    ///
182    /// The default implementation creates a closure that captures `self`
183    /// and calls its `apply` method. Types can override this method
184    /// to provide more efficient conversions.
185    ///
186    /// # Returns
187    ///
188    /// Returns a closure that implements `FnMut(T, U) -> R`
189    fn into_fn(self) -> impl FnMut(T, U) -> R
190    where
191        Self: Sized + 'static,
192    {
193        let mut trans = self;
194        move |t, u| trans.apply(t, u)
195    }
196
197    /// Converts bi-transformer to a mutable closure (`FnMut`) with an explicit
198    /// method name.
199    ///
200    /// This is a naming alias of [`StatefulBiTransformer::into_fn`] to avoid
201    /// confusion with non-stateful `into_fn` methods that typically return `Fn`.
202    fn into_mut_fn(self) -> impl FnMut(T, U) -> R
203    where
204        Self: Sized + 'static,
205    {
206        self.into_fn()
207    }
208
209    /// Converts to BoxBiTransformerOnce
210    ///
211    /// **⚠️ Consumes `self`**: The original bi-transformer becomes unavailable
212    /// after calling this method.
213    ///
214    /// # Default Implementation
215    ///
216    /// The default implementation wraps `self` in a `Box` and creates a
217    /// `BoxBiTransformerOnce`. Types can override this method to provide more
218    /// efficient conversions.
219    ///
220    /// # Returns
221    ///
222    /// Returns `BoxBiTransformerOnce<T, U, R>`
223    fn into_once(self) -> BoxBiTransformerOnce<T, U, R>
224    where
225        Self: Sized + 'static,
226    {
227        let mut trans = self;
228        BoxBiTransformerOnce::new(move |t, u| trans.apply(t, u))
229    }
230
231    /// Non-consuming conversion to `BoxStatefulBiTransformer` using `&self`.
232    ///
233    /// Default implementation clones `self` and delegates to `into_box`.
234    fn to_box(&self) -> BoxStatefulBiTransformer<T, U, R>
235    where
236        Self: Sized + Clone + 'static,
237    {
238        self.clone().into_box()
239    }
240
241    /// Non-consuming conversion to `RcStatefulBiTransformer` using `&self`.
242    ///
243    /// Default implementation clones `self` and delegates to `into_rc`.
244    fn to_rc(&self) -> RcStatefulBiTransformer<T, U, R>
245    where
246        Self: Sized + Clone + 'static,
247    {
248        self.clone().into_rc()
249    }
250
251    /// Non-consuming conversion to `ArcStatefulBiTransformer` using `&self`.
252    ///
253    /// Default implementation clones `self` and delegates to `into_arc`.
254    fn to_arc(&self) -> ArcStatefulBiTransformer<T, U, R>
255    where
256        Self: Sized + Clone + Send + 'static,
257    {
258        self.clone().into_arc()
259    }
260
261    /// Non-consuming conversion to a boxed function using `&self`.
262    ///
263    /// Returns a `Box<dyn FnMut(T, U) -> R>` that clones `self` and calls
264    /// `apply` inside the boxed closure.
265    fn to_fn(&self) -> impl FnMut(T, U) -> R
266    where
267        Self: Sized + Clone + 'static,
268    {
269        self.clone().into_fn()
270    }
271
272    /// Non-consuming conversion to a mutable closure (`FnMut`) with an explicit
273    /// method name.
274    ///
275    /// This is a naming alias of [`StatefulBiTransformer::to_fn`] and keeps the
276    /// same clone-based behavior.
277    fn to_mut_fn(&self) -> impl FnMut(T, U) -> R
278    where
279        Self: Sized + Clone + 'static,
280    {
281        self.to_fn()
282    }
283
284    /// Non-consuming conversion to `BoxBiTransformerOnce` using `&self`.
285    ///
286    /// Default implementation clones `self` and delegates to `into_once`.
287    fn to_once(&self) -> BoxBiTransformerOnce<T, U, R>
288    where
289        Self: Sized + Clone + 'static,
290    {
291        self.clone().into_once()
292    }
293}
qubit_function/transformers/stateful_bi_transformer.rs

qubit_function/transformers/
stateful_bi_transformer.rs
