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

qubit_function/functions/mutating_function/
rc_mutating_function.rs
