qubit_function/functions/stateful_mutating_function/
box_stateful_mutating_function.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxStatefulMutatingFunction` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// =======================================================================
16// 3. BoxStatefulMutatingFunction - Single Ownership Implementation
17// =======================================================================
18
19/// BoxStatefulMutatingFunction struct
20///
21/// A stateful mutating function implementation based on
22/// `Box<dyn FnMut(&mut T) -> R>` for single ownership scenarios. This is the
23/// simplest and most efficient stateful mutating function type when sharing
24/// is not required.
25///
26/// # Features
27///
28/// - **Single Ownership**: Not cloneable, ownership moves on use
29/// - **Zero Overhead**: No reference counting or locking
30/// - **Stateful**: Can modify captured environment (uses `FnMut`)
31/// - **Builder Pattern**: Method chaining consumes `self` naturally
32/// - **Factory Methods**: Convenient constructors for common patterns
33///
34/// # Use Cases
35///
36/// Choose `BoxStatefulMutatingFunction` when:
37/// - The function needs to maintain internal state
38/// - Building pipelines where ownership naturally flows
39/// - No need to share the function across contexts
40/// - Performance is critical and no sharing overhead is acceptable
41///
42/// # Performance
43///
44/// `BoxStatefulMutatingFunction` has the best performance among the three
45/// function types:
46/// - No reference counting overhead
47/// - No lock acquisition or runtime borrow checking
48/// - Direct function call through vtable
49/// - Minimal memory footprint (single pointer)
50///
51/// # Examples
52///
53/// ```rust
54/// use qubit_function::{StatefulMutatingFunction,
55///                       BoxStatefulMutatingFunction};
56///
57/// let mut counter = {
58///     let mut count = 0;
59///     BoxStatefulMutatingFunction::new(move |x: &mut i32| {
60///         count += 1;
61///         *x *= 2;
62///         count
63///     })
64/// };
65/// let mut value = 5;
66/// assert_eq!(counter.apply(&mut value), 1);
67/// assert_eq!(value, 10);
68/// ```
69///
70/// # Author
71///
72/// Haixing Hu
73pub struct BoxStatefulMutatingFunction<T, R> {
74    pub(super) function: Box<dyn FnMut(&mut T) -> R>,
75    pub(super) name: Option<String>,
76}
77
78impl<T, R> BoxStatefulMutatingFunction<T, R> {
79    // Generates: new(), new_with_name(), new_with_optional_name(), name(), set_name()
80    impl_function_common_methods!(
81        BoxStatefulMutatingFunction<T, R>,
82        (FnMut(&mut T) -> R + 'static),
83        |f| Box::new(f)
84    );
85
86    // Generates: when(), and_then(), compose()
87    impl_box_function_methods!(
88        BoxStatefulMutatingFunction<T, R>,
89        BoxConditionalStatefulMutatingFunction,
90        Function        // chains a non-mutating function after this mutating function
91    );
92}
93
94// Generates: Debug and Display implementations for BoxStatefulMutatingFunction<T, R>
95impl_function_debug_display!(BoxStatefulMutatingFunction<T, R>);
96
97// Generates: identity() method for BoxStatefulMutatingFunction<T, T>
98impl_function_identity_method!(BoxStatefulMutatingFunction<T, T>, mutating);
99
100// Implement StatefulMutatingFunction trait for BoxStatefulMutatingFunction<T, R>
101impl<T, R> StatefulMutatingFunction<T, R> for BoxStatefulMutatingFunction<T, R> {
102    fn apply(&mut self, t: &mut T) -> R {
103        (self.function)(t)
104    }
105
106    // Generates: into_box(), into_rc(), into_fn(), into_once()
107    impl_box_conversions!(
108        BoxStatefulMutatingFunction<T, R>,
109        RcStatefulMutatingFunction,
110        FnMut(&mut T) -> R,
111        BoxMutatingFunctionOnce
112    );
113}
qubit_function/functions/stateful_mutating_function/box_stateful_mutating_function.rs

qubit_function/functions/stateful_mutating_function/
box_stateful_mutating_function.rs
