qubit_function/macros/
box_conversions.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! # Box Conversions Macro
10//!
11//! Generate common conversion methods for all Box-based function wrappers.
12//!
13//! This macro uses a unified pattern to generate standard conversion methods
14//! for all Box-based function wrapper types (into_box, into_rc, into_fn,
15//! into_once).
16//!
17//! # Author
18//!
19//! Hu Haixing
20
21/// Implement common conversion methods for Box types
22///
23/// This macro generates standard conversion methods for Box-based function
24/// wrappers.
25///
26/// # Parameters
27///
28/// * `$box_type<$(generics),*>` - Box wrapper type (e.g., `BoxConsumer<T>`)
29/// * `$rc_type` - Corresponding Rc wrapper type (e.g., `RcConsumer`)
30/// * `$fn_trait` - Function trait (e.g., `Fn(&T)`, `Fn(&T) -> bool`)
31/// * `$once_type` - Corresponding once wrapper type (optional, e.g.,
32///   `BoxConsumerOnce`)
33///
34/// # Generated methods
35///
36/// * `into_box(self) -> BoxType` - Zero-cost conversion, returns self
37/// * `into_rc(self) -> RcType` - Convert to Rc-based wrapper
38/// * `into_fn(self) -> impl FnTrait` - Extract underlying function
39/// * `into_once(self) -> OnceType` - Convert to once wrapper (only when
40///   once_type is provided)
41///
42/// # Examples
43///
44/// ```ignore
45/// // 3-parameter version (no once type)
46/// impl_box_conversions!(
47///     BoxPredicate<T>,
48///     RcPredicate,
49///     Fn(&T) -> bool
50/// );
51///
52/// // 4-parameter version (with once type)
53/// impl_box_conversions!(
54///     BoxConsumer<T>,
55///     RcConsumer,
56///     Fn(&T),
57///     BoxConsumerOnce
58/// );
59/// ```
60///
61/// # Author
62///
63/// Hu Haixing
64macro_rules! impl_box_conversions {
65    // 3-parameter pattern: box_type, rc_type, fn_trait (no once_type)
66    (
67        $box_type:ident < $($generics:ident),* >,
68        $rc_type:ident,
69        $fn_trait:path
70    ) => {
71        #[inline]
72        fn into_box(self) -> $box_type<$($generics),*>
73        {
74            self
75        }
76
77        #[inline]
78        fn into_rc(self) -> $rc_type<$($generics),*>
79        where
80            $($generics: 'static),*
81        {
82            $rc_type::new_with_optional_name(self.function, self.name)
83        }
84
85        #[inline]
86        fn into_fn(self) -> impl $fn_trait
87        {
88            self.function
89        }
90    };
91
92    // 4-parameter pattern: box_type, rc_type, fn_trait, once_type
93    // Reuse 3-parameter version to generate into_box, into_rc, into_fn
94    (
95        $box_type:ident < $($generics:ident),* >,
96        $rc_type:ident,
97        $fn_trait:path,
98        $once_type:ident
99    ) => {
100        // Reuse 3-parameter version to generate into_box, into_rc, into_fn
101        impl_box_conversions!(
102            $box_type < $($generics),* >,
103            $rc_type,
104            $fn_trait
105        );
106
107        #[inline]
108        fn into_once(self) -> $once_type<$($generics),*>
109        where
110            $($generics: 'static),*
111        {
112            $once_type::new_with_optional_name(self.function, self.name)
113        }
114    };
115}
116
117pub(crate) use impl_box_conversions;
118
119/// Implement common conversion methods for Box*Once types
120///
121/// This macro generates standard conversion methods for all Box*Once types
122/// that implement their respective traits (into_box, into_fn).
123///
124/// The macro unifies the pattern for both void-returning functions (like
125/// Consumer, Mutator) and value-returning functions (like Function,
126/// Transformer, Supplier).
127///
128/// # Parameters
129///
130/// * `$box_type_with_generics` - Box type with generics (e.g.,
131///   `BoxConsumerOnce<T>`, `BoxBiConsumerOnce<T, U>`)
132/// * `$trait_name` - Trait name (for documentation, unused in expansion)
133/// * `$fn_trait` - Function trait type (e.g., `FnOnce(&T)`,
134///   `FnOnce(&T) -> R`, `FnOnce() -> T`)
135///
136/// # Generated methods
137///
138/// * `into_box(self) -> BoxType` - Zero-cost conversion, returns self
139/// * `into_fn(self) -> impl FnOnce(...)` - Extract underlying function
140///
141/// # Examples
142///
143/// ```ignore
144/// // Consumer: (&T) -> ()
145/// impl_box_once_conversions!(BoxConsumerOnce<T>, ConsumerOnce, FnOnce(&T));
146///
147/// // BiConsumer: (&T, &U) -> ()
148/// impl_box_once_conversions!(BoxBiConsumerOnce<T, U>, BiConsumerOnce,
149///     FnOnce(&T, &U));
150///
151/// // Function: (&T) -> R
152/// impl_box_once_conversions!(BoxFunctionOnce<T, R>, FunctionOnce,
153///     FnOnce(&T) -> R);
154///
155/// // Transformer: (T) -> R
156/// impl_box_once_conversions!(BoxTransformerOnce<T, R>, TransformerOnce,
157///     FnOnce(T) -> R);
158///
159/// // Supplier: () -> T
160/// impl_box_once_conversions!(BoxSupplierOnce<T>, SupplierOnce, FnOnce() -> T);
161/// ```
162///
163/// # Author
164///
165/// Hu Haixing
166macro_rules! impl_box_once_conversions {
167    (
168        $box_type:ident < $($generics:ident),* >,
169        $trait_name:ident,
170        $fn_trait:path
171    ) => {
172        #[inline]
173        fn into_box(self) -> $box_type<$($generics),*>
174        {
175            self
176        }
177
178        #[inline]
179        fn into_fn(self) -> impl $fn_trait
180        {
181            self.function
182        }
183    };
184}
185
186pub(crate) use impl_box_once_conversions;
qubit_function/macros/box_conversions.rs

qubit_function/macros/
box_conversions.rs
