qubit_function/transformers/
transformer_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! # TransformerOnce Types
10//!
11//! Provides Rust implementations of consuming transformer traits similar to
12//! Rust's `FnOnce` trait, but with value-oriented semantics for functional
13//! programming patterns.
14//!
15//! This module provides the `TransformerOnce<T, R>` trait and one-time use
16//! implementations:
17//!
18//! - [`BoxTransformerOnce`]: Single ownership, one-time use
19//!
20//! # Author
21//!
22//! Haixing Hu
23
24use crate::macros::{
25    impl_box_once_conversions,
26    impl_closure_once_trait,
27};
28use crate::predicates::predicate::{
29    BoxPredicate,
30    Predicate,
31};
32use crate::transformers::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
41mod box_transformer_once;
42pub use box_transformer_once::BoxTransformerOnce;
43mod fn_transformer_once_ops;
44pub use fn_transformer_once_ops::FnTransformerOnceOps;
45mod unary_operator_once;
46pub use unary_operator_once::UnaryOperatorOnce;
47mod box_unary_operator_once;
48pub use box_unary_operator_once::BoxUnaryOperatorOnce;
49mod box_conditional_transformer_once;
50pub use box_conditional_transformer_once::BoxConditionalTransformerOnce;
51
52// ============================================================================
53// Core Trait
54// ============================================================================
55
56/// TransformerOnce trait - consuming transformation that takes ownership
57///
58/// Defines the behavior of a consuming transformer: converting a value of
59/// type `T` to a value of type `R` by taking ownership of both self and the
60/// input. This trait is analogous to `FnOnce(T) -> R`.
61///
62/// # Type Parameters
63///
64/// * `T` - The type of the input value (consumed)
65/// * `R` - The type of the output value
66///
67/// # Author
68///
69/// Haixing Hu
70pub trait TransformerOnce<T, R> {
71    /// Transforms the input value, consuming both self and input
72    ///
73    /// # Parameters
74    ///
75    /// * `input` - The input value (consumed)
76    ///
77    /// # Returns
78    ///
79    /// The transformed output value
80    fn apply(self, input: T) -> R;
81
82    /// Converts to BoxTransformerOnce
83    ///
84    /// **⚠️ Consumes `self`**: The original transformer becomes unavailable
85    /// after calling this method.
86    ///
87    /// # Returns
88    ///
89    /// Returns `BoxTransformerOnce<T, R>`
90    ///
91    /// # Examples
92    ///
93    /// ```rust
94    /// use qubit_function::TransformerOnce;
95    ///
96    /// let double = |x: i32| x * 2;
97    /// let boxed = double.into_box();
98    /// assert_eq!(boxed.apply(21), 42);
99    /// ```
100    fn into_box(self) -> BoxTransformerOnce<T, R>
101    where
102        Self: Sized + 'static,
103    {
104        BoxTransformerOnce::new(move |input: T| self.apply(input))
105    }
106
107    /// Converts transformer to a closure
108    ///
109    /// **⚠️ Consumes `self`**: The original transformer becomes unavailable
110    /// after calling this method.
111    ///
112    /// # Returns
113    ///
114    /// Returns a closure that implements `FnOnce(T) -> R`
115    ///
116    /// # Examples
117    ///
118    /// ```rust
119    /// use qubit_function::TransformerOnce;
120    ///
121    /// let double = |x: i32| x * 2;
122    /// let func = double.into_fn();
123    /// assert_eq!(func(21), 42);
124    /// ```
125    fn into_fn(self) -> impl FnOnce(T) -> R
126    where
127        Self: Sized + 'static,
128    {
129        move |input: T| self.apply(input)
130    }
131
132    /// Converts to BoxTransformerOnce without consuming self
133    ///
134    /// **📌 Borrows `&self`**: The original transformer remains usable
135    /// after calling this method.
136    ///
137    /// # Default Implementation
138    ///
139    /// The default implementation creates a new `BoxTransformerOnce` that
140    /// captures a clone. Types implementing `Clone` can override this method
141    /// to provide more efficient conversions.
142    ///
143    /// # Returns
144    ///
145    /// Returns `BoxTransformerOnce<T, R>`
146    ///
147    /// # Examples
148    ///
149    /// ```rust
150    /// use qubit_function::TransformerOnce;
151    ///
152    /// let double = |x: i32| x * 2;
153    /// let boxed = double.to_box();
154    /// assert_eq!(boxed.apply(21), 42);
155    /// ```
156    fn to_box(&self) -> BoxTransformerOnce<T, R>
157    where
158        Self: Clone + 'static,
159    {
160        self.clone().into_box()
161    }
162
163    /// Converts transformer to a closure without consuming self
164    ///
165    /// **📌 Borrows `&self`**: The original transformer remains usable
166    /// after calling this method.
167    ///
168    /// # Default Implementation
169    ///
170    /// The default implementation creates a closure that captures a
171    /// clone of `self` and calls its `transform` method. Types can
172    /// override this method to provide more efficient conversions.
173    ///
174    /// # Returns
175    ///
176    /// Returns a closure that implements `FnOnce(T) -> R`
177    ///
178    /// # Examples
179    ///
180    /// ```rust
181    /// use qubit_function::TransformerOnce;
182    ///
183    /// let double = |x: i32| x * 2;
184    /// let func = double.to_fn();
185    /// assert_eq!(func(21), 42);
186    /// ```
187    fn to_fn(&self) -> impl FnOnce(T) -> R
188    where
189        Self: Clone + 'static,
190    {
191        self.clone().into_fn()
192    }
193}
qubit_function/transformers/transformer_once.rs

qubit_function/transformers/
transformer_once.rs
