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

qubit_function/mutators/mutator/
box_mutator.rs
