qubit_function/mutators/stateful_mutator/
box_stateful_mutator.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxStatefulMutator` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// 3. BoxMutator - Single Ownership Implementation
17// ============================================================================
18
19/// BoxMutator struct
20///
21/// A mutator implementation based on `Box<dyn FnMut(&mut T)>` for single
22/// ownership scenarios. This is the simplest and most efficient mutator
23/// type when sharing is not required.
24///
25/// # Features
26///
27/// - **Single Ownership**: Not cloneable, ownership moves on use
28/// - **Zero Overhead**: No reference counting or locking
29/// - **Mutable State**: Can modify captured environment via `FnMut`
30/// - **Builder Pattern**: Method chaining consumes `self` naturally
31/// - **Factory Methods**: Convenient constructors for common patterns
32///
33/// # Use Cases
34///
35/// Choose `BoxMutator` when:
36/// - The mutator is used only once or in a linear flow
37/// - Building pipelines where ownership naturally flows
38/// - No need to share the mutator across contexts
39/// - Performance is critical and no sharing overhead is acceptable
40///
41/// # Performance
42///
43/// `BoxMutator` has the best performance among the three mutator types:
44/// - No reference counting overhead
45/// - No lock acquisition or runtime borrow checking
46/// - Direct function call through vtable
47/// - Minimal memory footprint (single pointer)
48///
49/// # Examples
50///
51/// ```rust
52/// use qubit_function::{Mutator, BoxMutator};
53///
54/// let mut mutator = BoxMutator::new(|x: &mut i32| *x *= 2);
55/// let mut value = 5;
56/// mutator.apply(&mut value);
57/// assert_eq!(value, 10);
58/// ```
59///
60/// # Author
61///
62/// Haixing Hu
63pub struct BoxStatefulMutator<T> {
64    pub(super) function: Box<dyn FnMut(&mut T)>,
65    pub(super) name: Option<String>,
66}
67
68impl<T> BoxStatefulMutator<T> {
69    impl_mutator_common_methods!(BoxStatefulMutator<T>, (FnMut(&mut T) + 'static), |f| {
70        Box::new(f)
71    });
72
73    // Generate box mutator methods (when, and_then, or_else, etc.)
74    impl_box_mutator_methods!(
75        BoxStatefulMutator<T>,
76        BoxConditionalStatefulMutator,
77        StatefulMutator
78    );
79}
80
81impl<T> StatefulMutator<T> for BoxStatefulMutator<T> {
82    fn apply(&mut self, value: &mut T) {
83        (self.function)(value)
84    }
85
86    // Generates: into_box(), into_rc(), into_fn(), into_once()
87    impl_box_conversions!(
88        BoxStatefulMutator<T>,
89        RcStatefulMutator,
90        FnMut(&mut T),
91        BoxMutatorOnce
92    );
93}
94
95// Generate Debug and Display trait implementations
96impl_mutator_debug_display!(BoxStatefulMutator<T>);
qubit_function/mutators/stateful_mutator/box_stateful_mutator.rs

qubit_function/mutators/stateful_mutator/
box_stateful_mutator.rs
