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

qubit_function/transformers/
bi_transformer_once.rs
