qubit_function/functions/mutating_function_once/
box_conditional_mutating_function_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxConditionalMutatingFunctionOnce` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// BoxConditionalMutatingFunctionOnce - Box-based Conditional Mutating Function
17// ============================================================================
18
19/// BoxConditionalMutatingFunctionOnce struct
20///
21/// A conditional consuming transformer that only executes when a predicate is
22/// satisfied. Uses `BoxMutatingFunctionOnce` and `BoxPredicate` for single
23/// ownership semantics.
24///
25/// This type is typically created by calling `BoxMutatingFunctionOnce::when()` and
26/// is designed to work with the `or_else()` method to create if-then-else
27/// logic.
28///
29/// # Features
30///
31/// - **Single Ownership**: Not cloneable, consumes `self` on use
32/// - **One-time Use**: Can only be called once
33/// - **Conditional Execution**: Only transforms when predicate returns `true`
34/// - **Chainable**: Can add `or_else` branch to create if-then-else logic
35///
36/// # Examples
37///
38/// ## With or_else Branch
39///
40/// ```rust
41/// use qubit_function::{MutatingFunctionOnce, BoxMutatingFunctionOnce};
42///
43/// let double = BoxMutatingFunctionOnce::new(|x: &mut i32| {
44///     *x *= 2;
45///     *x
46/// });
47/// let negate = BoxMutatingFunctionOnce::new(|x: &mut i32| {
48///     *x = -*x;
49///     *x
50/// });
51/// let conditional = double.when(|x: &i32| *x > 0).or_else(negate);
52/// let mut positive = 5;
53/// assert_eq!(conditional.apply(&mut positive), 10); // when branch executed
54///
55/// let double2 = BoxMutatingFunctionOnce::new(|x: &mut i32| {
56///     *x *= 2;
57///     *x
58/// });
59/// let negate2 = BoxMutatingFunctionOnce::new(|x: &mut i32| {
60///     *x = -*x;
61///     *x
62/// });
63/// let conditional2 = double2.when(|x: &i32| *x > 0).or_else(negate2);
64/// let mut negative = -5;
65/// assert_eq!(conditional2.apply(&mut negative), 5); // or_else branch executed
66/// ```
67///
68/// # Author
69///
70/// Haixing Hu
71pub struct BoxConditionalMutatingFunctionOnce<T, R> {
72    pub(super) function: BoxMutatingFunctionOnce<T, R>,
73    pub(super) predicate: BoxPredicate<T>,
74}
75
76// Use macro to generate conditional function implementations
77impl_box_conditional_function!(
78    BoxConditionalMutatingFunctionOnce<T, R>,
79    BoxMutatingFunctionOnce,
80    MutatingFunctionOnce
81);
82
83// Use macro to generate conditional function debug and display implementations
84impl_conditional_function_debug_display!(BoxConditionalMutatingFunctionOnce<T, R>);
qubit_function/functions/mutating_function_once/box_conditional_mutating_function_once.rs

qubit_function/functions/mutating_function_once/
box_conditional_mutating_function_once.rs
