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

qubit_function/mutators/stateful_mutator/
box_stateful_mutator.rs
