qubit-function 0.18.2

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! # Box Mutator Methods Macro
//!
//! Generates `when` and `and_then` methods for Box-based mutators.
//!
//! Generates `when` and `and_then` methods for Box-based mutators that consume
//! `self` because the boxed mutator cannot be cloned.
//!
//! This macro supports single-parameter mutators through
//! pattern matching on the struct signature.
//!
//! # Parameters
//!
//! * `$struct_name<$t>` - The mutator wrapper type with one type parameter,
//!   such as `BoxMutator<T>`
//! * `$conditional_type` - The conditional mutator type for when (e.g.,
//!   BoxConditionalMutator)
//! * `$mutator_trait` - Mutator trait name (e.g., Mutator, MutatorOnce)
//!
//! # Parameter Usage Comparison
//!
//! | Mutator Type | Struct Signature | `$conditional_type` | `$mutator_trait` |
//! |--------------|-----------------|----------------|-------------------|
//! | **Mutator** | `BoxMutator<T>` | BoxConditionalMutator | Mutator |
//! | **MutatorOnce** | `BoxMutatorOnce<T>` | BoxConditionalMutatorOnce | MutatorOnce |
//! | **StatefulMutator** | `BoxStatefulMutator<T>` | BoxConditionalStatefulMutator | StatefulMutator |
//!
//! # Examples
//!
//! ```text
//! // Single-parameter mutator
//! // impl_box_mutator_methods!(
//! //     BoxMutator<T>,
//! //     BoxConditionalMutator,
//! //     Mutator
//! // );
//! ```

/// Generates `when` and `and_then` methods for Box-based mutators.
///
/// Invoke this macro inside the target wrapper's `impl` block. The `when`
/// method creates a conditional mutator, and `and_then` chains a subsequent
/// mutator after the current one. Both methods consume `self` because the
/// boxed mutator cannot be cloned.
///
/// This macro supports single-parameter mutators through
/// pattern matching on the struct signature.
///
/// # Parameters
///
/// * `$struct_name<$t>` - The mutator wrapper type with one type parameter,
///   such as `BoxMutator<T>`
/// * `$conditional_type` - The conditional mutator type for when (e.g.,
///   BoxConditionalMutator)
/// * `$mutator_trait` - Mutator trait name (e.g., Mutator, MutatorOnce)
///
/// # Parameter Usage Comparison
///
/// | Mutator Type | Struct Signature | `$conditional_type` | `$mutator_trait` |
/// |--------------|-----------------|----------------|-------------------|
/// | **Mutator** | `BoxMutator<T>` | BoxConditionalMutator | Mutator |
/// | **MutatorOnce** | `BoxMutatorOnce<T>` | BoxConditionalMutatorOnce | MutatorOnce |
/// | **StatefulMutator** | `BoxStatefulMutator<T>` | BoxConditionalStatefulMutator | StatefulMutator |
///
/// # Usage Location
///
/// This macro should be used inside an impl block for the struct type.
///
/// # Examples
///
/// ```text
/// // impl<T> BoxMutator<T> {
/// //     // Inside an impl block
/// //     impl_box_mutator_methods!(
/// //         BoxMutator<T>,
/// //         BoxConditionalMutator,
/// //         Mutator
/// //     );
/// // }
/// ```
macro_rules! impl_box_mutator_methods {
    (@and_then Mutator, $struct_name:ident, $first:expr, $after:expr, $t:ident) => {{
        let first = $first;
        let after = $after;
        $struct_name::new(move |t: &mut $t| {
            first.apply(t);
            after.apply(t);
        })
    }};

    (@and_then MutatorOnce, $struct_name:ident, $first:expr, $after:expr, $t:ident) => {{
        let first = $first;
        let after = $after;
        $struct_name::new(move |t: &mut $t| {
            first.apply(t);
            after.apply(t);
        })
    }};

    (@and_then StatefulMutator, $struct_name:ident, $first:expr, $after:expr, $t:ident) => {{
        let mut first = $first;
        let mut after = $after;
        $struct_name::new(move |t: &mut $t| {
            first.apply(t);
            after.apply(t);
        })
    }};

    // Single generic parameter - Mutator
    ($struct_name:ident < $t:ident >, $conditional_type:ident, $mutator_trait:ident) => {
        /// Creates a conditional mutator that executes based on predicate
        /// result.
        ///
        /// # Parameters
        ///
        /// * `predicate` - The predicate to determine whether to execute
        ///   the mutation operation
        ///
        /// # Returns
        ///
        /// Returns a conditional mutator that only executes when the
        /// predicate returns `true`.
        ///
        /// # Examples
        ///
        /// ```rust
        /// use std::sync::Arc;
        /// use std::sync::atomic::{AtomicI32, Ordering};
        /// use qubit_function::mutators::*;
        ///
        /// let counter = Arc::new(AtomicI32::new(0));
        /// let mutator = BoxMutator::new({
        ///     let counter = Arc::clone(&counter);
        ///     move |value: &mut i32| {
        ///         *value += counter.fetch_add(1, Ordering::SeqCst);
        ///     }
        /// });
        ///
        /// let conditional = mutator.when(|value: &i32| *value > 0);
        /// let mut val = 1;
        /// conditional.apply(&mut val);  // val = 2 (1 + 1)
        /// let mut val2 = -1;
        /// conditional.apply(&mut val2); // not executed, val2 remains -1
        /// ```
        pub fn when<P>(self, predicate: P) -> $conditional_type<$t>
        where
            $t: 'static,
            P: Predicate<$t> + 'static,
        {
            $conditional_type {
                mutator: self,
                predicate: $crate::BoxPredicate::new(predicate),
            }
        }

        /// Chains execution with another mutator, executing the current
        /// mutator first, then the subsequent mutator.
        ///
        /// # Parameters
        ///
        /// * `after` - The subsequent mutator to execute after the current
        ///   mutator completes
        ///
        /// # Returns
        ///
        /// Returns a new mutator that executes the current mutator and
        /// the subsequent mutator in sequence.
        ///
        /// # Examples
        ///
        /// ```rust
        /// use std::sync::Arc;
        /// use std::sync::atomic::{AtomicI32, Ordering};
        /// use qubit_function::mutators::*;
        ///
        /// let counter1 = Arc::new(AtomicI32::new(0));
        /// let counter2 = Arc::new(AtomicI32::new(0));
        ///
        /// let mutator1 = BoxMutator::new({
        ///     let counter = Arc::clone(&counter1);
        ///     move |value: &mut i32| {
        ///         *value += counter.fetch_add(1, Ordering::SeqCst);
        ///     }
        /// });
        ///
        /// let mutator2 = BoxMutator::new({
        ///     let counter = Arc::clone(&counter2);
        ///     move |value: &mut i32| {
        ///         *value += counter.fetch_add(1, Ordering::SeqCst);
        ///     }
        /// });
        ///
        /// let chained = mutator1.and_then(mutator2);
        /// let mut val = 0;
        /// chained.apply(&mut val);
        /// // val = 2 (0 + 1 + 1)
        /// ```
        pub fn and_then<M>(self, after: M) -> $struct_name<$t>
        where
            Self: Sized + 'static,
            $t: 'static,
            M: $mutator_trait<$t> + 'static,
        {
            impl_box_mutator_methods!(@and_then $mutator_trait, $struct_name, self, after, $t)
        }
    };
}

pub(crate) use impl_box_mutator_methods;