qubit_function/mutators/mutator/
box_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 `BoxMutator` 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 stateless mutator implementation based on `Box<dyn Fn(&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/// - **Stateless**: Cannot modify captured environment (uses `Fn` not `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 for stateless transformations
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 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 BoxMutator<T> {
64    pub(super) function: Box<dyn Fn(&mut T)>,
65    pub(super) name: Option<String>,
66}
67
68impl<T> BoxMutator<T> {
69    // Generate common mutator methods (new, new_with_name, name, set_name, noop)
70    impl_mutator_common_methods!(BoxMutator<T>, (Fn(&mut T) + 'static), |f| Box::new(f));
71
72    // Generate box mutator methods (when, and_then, or_else, etc.)
73    impl_box_mutator_methods!(BoxMutator<T>, BoxConditionalMutator, Mutator);
74}
75
76impl<T> Mutator<T> for BoxMutator<T> {
77    fn apply(&self, value: &mut T) {
78        (self.function)(value)
79    }
80
81    // Generates: into_box(), into_rc(), into_fn(), into_once()
82    impl_box_conversions!(BoxMutator<T>, RcMutator, Fn(&mut T), BoxMutatorOnce);
83}
84
85// Generate Debug and Display trait implementations
86impl_mutator_debug_display!(BoxMutator<T>);
qubit_function/mutators/mutator/box_mutator.rs

qubit_function/mutators/mutator/
box_mutator.rs
