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

qubit_function/transformers/
transformer_once.rs
