qubit_function/functions/stateful_mutating_function/arc_conditional_stateful_mutating_function.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 `ArcConditionalStatefulMutatingFunction` public type.
12
13#![allow(unused_imports)]
14
15use super::*;
16
17// ============================================================================
18// ArcConditionalStatefulMutatingFunction - Arc-based Conditional Stateful Mutating Function
19// ============================================================================
20
21/// ArcConditionalStatefulMutatingFunction struct
22///
23/// A thread-safe conditional function that only executes when a predicate is
24/// satisfied. Uses `ArcStatefulMutatingFunction` and `ArcPredicate` for shared ownership
25/// across threads.
26///
27/// This type is typically created by calling `ArcStatefulMutatingFunction::when()` and is
28/// designed to work with the `or_else()` method to create if-then-else logic.
29///
30/// # Features
31///
32/// - **Shared Ownership**: Cloneable via `Arc`, multiple owners allowed
33/// - **Thread-Safe**: Implements `Send + Sync`, safe for concurrent use
34/// - **Conditional Execution**: Only transforms when predicate returns `true`
35/// - **Chainable**: Can add `or_else` branch to create if-then-else logic
36///
37/// # Examples
38///
39/// ```rust
40/// use qubit_function::{StatefulMutatingFunction, ArcStatefulMutatingFunction};
41///
42/// let double = ArcStatefulMutatingFunction::new(|x: &mut i32| {
43/// *x *= 2;
44/// *x
45/// });
46/// let identity = ArcStatefulMutatingFunction::<i32, i32>::identity();
47/// let mut conditional = double.when(|x: &i32| *x > 0).or_else(identity);
48///
49/// let mut conditional_clone = conditional.clone();
50///
51/// let mut positive = 5;
52/// let mut negative = -5;
53/// assert_eq!(conditional.apply(&mut positive), 10);
54/// assert_eq!(conditional_clone.apply(&mut negative), -5);
55/// ```
56///
57pub struct ArcConditionalStatefulMutatingFunction<T, R> {
58 pub(super) function: ArcStatefulMutatingFunction<T, R>,
59 pub(super) predicate: ArcPredicate<T>,
60}
61
62// Use macro to generate conditional function implementations
63impl_shared_conditional_function!(
64 ArcConditionalStatefulMutatingFunction<T, R>,
65 ArcStatefulMutatingFunction,
66 StatefulMutatingFunction,
67 Send + Sync + 'static
68);
69
70// Use macro to generate conditional function clone implementations
71impl_conditional_function_clone!(ArcConditionalStatefulMutatingFunction<T, R>);
72
73// Use macro to generate conditional function debug and display implementations
74impl_conditional_function_debug_display!(ArcConditionalStatefulMutatingFunction<T, R>);