qubit_function/functions/stateful_mutating_function/
rc_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 `RcStatefulMutatingFunction` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// =======================================================================
16// 4. RcStatefulMutatingFunction - Single-Threaded Shared Ownership
17// =======================================================================
18
19/// RcStatefulMutatingFunction struct
20///
21/// A stateful mutating function implementation based on
22/// `Rc<RefCell<dyn FnMut(&mut T) -> R>>` for single-threaded shared
23/// ownership scenarios. This type allows multiple references to the same
24/// function without the overhead of thread safety.
25///
26/// # Features
27///
28/// - **Shared Ownership**: Cloneable via `Rc`, multiple owners allowed
29/// - **Single-Threaded**: Not thread-safe, cannot be sent across threads
30/// - **Stateful**: Can modify captured environment (uses `FnMut`)
31/// - **Chainable**: Method chaining via `&self` (non-consuming)
32/// - **Performance**: More efficient than `ArcStatefulMutatingFunction` (no
33///   locking)
34///
35/// # Use Cases
36///
37/// Choose `RcStatefulMutatingFunction` when:
38/// - The function needs to be shared within a single thread for stateful
39///   operations
40/// - Thread safety is not required
41/// - Performance is important (avoiding lock overhead)
42///
43/// # Examples
44///
45/// ```rust
46/// use qubit_function::{StatefulMutatingFunction,
47///                       RcStatefulMutatingFunction};
48///
49/// let counter = {
50///     let mut count = 0;
51///     RcStatefulMutatingFunction::new(move |x: &mut i32| {
52///         count += 1;
53///         *x *= 2;
54///         count
55///     })
56/// };
57/// let mut clone = counter.clone();
58///
59/// let mut value = 5;
60/// assert_eq!(clone.apply(&mut value), 1);
61/// ```
62///
63/// # Author
64///
65/// Haixing Hu
66pub struct RcStatefulMutatingFunction<T, R> {
67    pub(super) function: RcStatefulMutatingFunctionFn<T, R>,
68    pub(super) name: Option<String>,
69}
70
71impl<T, R> RcStatefulMutatingFunction<T, R> {
72    // Generates: new(), new_with_name(), new_with_optional_name(), name(), set_name()
73    impl_function_common_methods!(
74        RcStatefulMutatingFunction<T, R>,
75        (FnMut(&mut T) -> R + 'static),
76        |f| Rc::new(RefCell::new(f))
77    );
78
79    // Generates: when(), and_then(), compose()
80    impl_shared_function_methods!(
81        RcStatefulMutatingFunction<T, R>,
82        RcConditionalStatefulMutatingFunction,
83        into_rc,
84        Function,  // chains a non-mutating function after this mutating function
85        'static
86    );
87}
88
89// Generates: Clone implementation for RcStatefulMutatingFunction<T, R>
90impl_function_clone!(RcStatefulMutatingFunction<T, R>);
91
92// Generates: Debug and Display implementations for RcStatefulMutatingFunction<T, R>
93impl_function_debug_display!(RcStatefulMutatingFunction<T, R>);
94
95// Generates: identity() method for RcStatefulMutatingFunction<T, T>
96impl_function_identity_method!(RcStatefulMutatingFunction<T, T>, mutating);
97
98// Implement StatefulMutatingFunction trait for RcStatefulMutatingFunction<T, R>
99impl<T, R> StatefulMutatingFunction<T, R> for RcStatefulMutatingFunction<T, R> {
100    fn apply(&mut self, t: &mut T) -> R {
101        (self.function.borrow_mut())(t)
102    }
103
104    // Use macro to implement conversion methods
105    impl_rc_conversions!(
106        RcStatefulMutatingFunction<T, R>,
107        BoxStatefulMutatingFunction,
108        BoxMutatingFunctionOnce,
109        FnMut(input: &mut T) -> R
110    );
111}
qubit_function/functions/stateful_mutating_function/rc_stateful_mutating_function.rs

qubit_function/functions/stateful_mutating_function/
rc_stateful_mutating_function.rs
