qubit-function 0.14.0

/*******************************************************************************
 *
 *    Copyright (c) 2025 - 2026 Haixing Hu.
 *
 *    SPDX-License-Identifier: Apache-2.0
 *
 *    Licensed under the Apache License, Version 2.0.
 *
 ******************************************************************************/
//! # Box Conditional Function Macro
//!
//! Generates Box-based Conditional Function implementations
//!
//! For Box-based conditional functions, generates `or_else` methods,
//! as well as complete Function/BiFunction trait implementations.
//!
//! Box type characteristics:
//! - `or_else` function self (because Box cannot Clone)
//!
//! # Parameters
//!
//! * `$struct_name<$generics>` - Struct name with generic parameters
//! * `$box_function_type` - Function wrapper type name
//! * `$else_function_trait` - The name of the else function trait (e.g., Function, BiFunction)
//!
//! # Usage Examples
//!
//! ```text
//! // The `impl_box_conditional_function` macro is crate-private.
//! // Its usage pattern in crate source is:
//! //
//! // impl_box_conditional_function!(
//! //     BoxConditionalFunction<T, R>,
//! //     BoxFunction,
//! //     Function
//! // );
//! //
//! // impl_box_conditional_function!(
//! //     BoxConditionalBiFunction<T, U, R>,
//! //     BoxBiFunction,
//! //     BiFunction
//! // );
//! ```
//!

/// Generates Box-based Conditional Function implementations
///
/// This macro should be used at the top level (outside of any impl block) as
/// it generates a complete impl block with methods for the specified struct.
/// For Box-based conditional functions, generates `or_else` methods,
/// as well as complete Function/BiFunction trait implementations.
///
/// Box type characteristics:
/// - `or_else` consume self (because Box cannot Clone)
/// - Does not implement `into_arc()` (because Box types are not Send + Sync)
/// - Does not implement `to_xxx()` methods (because Box types cannot Clone)
///
/// # Parameters
///
/// * `$struct_name<$generics>` - Struct name with generic parameters
/// * `$box_function_type` - Function wrapper type name
/// * `$else_function_trait` - The name of the else function trait (e.g., Function, BiFunction)
///
/// # Usage Examples
///
/// ```text
/// // Two-parameter Function
/// // `impl_box_conditional_function!` is crate-private and expanded internally.
/// // impl_box_conditional_function!(
/// //     BoxConditionalFunction<T, R>,
/// //     BoxFunction,
/// //     Function
/// // );
///
/// // Three-parameter BiFunction
/// // impl_box_conditional_function!(
/// //     BoxConditionalBiFunction<T, U, R>,
/// //     BoxBiFunction,
/// //     BiFunction
/// // );
/// ```
///
macro_rules! impl_box_conditional_function {
    (@let_function Function, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function FunctionOnce, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function StatefulFunction, $name:ident, $value:expr) => {
        let mut $name = $value;
    };

    (@let_function MutatingFunction, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function MutatingFunctionOnce, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function StatefulMutatingFunction, $name:ident, $value:expr) => {
        let mut $name = $value;
    };

    (@let_function BiFunction, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function BiFunctionOnce, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function StatefulBiFunction, $name:ident, $value:expr) => {
        let mut $name = $value;
    };

    (@let_function BiMutatingFunction, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function BiMutatingFunctionOnce, $name:ident, $value:expr) => {
        let $name = $value;
    };

    (@let_function StatefulBiMutatingFunction, $name:ident, $value:expr) => {
        let mut $name = $value;
    };

    // Two generic parameters - Function
    (
        $struct_name:ident<$t:ident, $r:ident>,
        $box_function_type:ident,
        $else_function_trait:ident
    ) => {
        impl<$t, $r> $struct_name<$t, $r> {
            /// Provides an alternative function for when the predicate is not satisfied
            ///
            /// Combines the current conditional function with an alternative function
            /// into a new function that implements the following semantics:
            ///
            /// When the returned function is called with an argument:
            /// - If the predicate is satisfied, it executes the internal function
            /// - If the predicate is NOT satisfied, it executes the alternative function
            ///
            /// # Parameters
            ///
            /// * `else_function` - The alternative function to execute when predicate fails
            ///
            /// # Returns
            ///
            /// Returns a new function that handles both conditional branches
            ///
            /// # Examples
            ///
            /// ```rust
            /// use qubit_function::{BoxFunction, Function};
            ///
            /// let func = BoxFunction::new(|x: &i32| x * 2);
            /// let alternative = BoxFunction::new(|x: &i32| x + 10);
            ///
            /// let conditional = func.when(|x: &i32| *x > 0).or_else(alternative);
            ///
            /// assert_eq!(conditional.apply(&5), 10);  // 5 * 2 = 10
            /// assert_eq!(conditional.apply(&-3), 7);  // -3 + 10 = 7
            /// ```
            pub fn or_else<F>(self, else_function: F) -> $box_function_type<$t, $r>
            where
                $t: 'static,
                $r: 'static,
                F: $else_function_trait<$t, $r> + 'static,
            {
                let predicate = self.predicate;
                impl_box_conditional_function!(@let_function $else_function_trait, then_function, self.function);
                impl_box_conditional_function!(@let_function $else_function_trait, else_function, else_function);
                $box_function_type::new(move |t| {
                    if predicate.test(t) {
                        then_function.apply(t)
                    } else {
                        else_function.apply(t)
                    }
                })
            }
        }
    };

    // Three generic parameters - BiFunction
    (
        $struct_name:ident<$t:ident, $u:ident, $r:ident>,
        $box_function_type:ident,
        $else_function_trait:ident
    ) => {
        impl<$t, $u, $r> $struct_name<$t, $u, $r> {
            /// Provides an alternative function for when the predicate is not satisfied
            ///
            /// Combines the current conditional bi-function with an alternative bi-function
            /// into a new bi-function that implements the following semantics:
            ///
            /// When the returned bi-function is called with two arguments:
            /// - If the predicate is satisfied, it executes the internal bi-function
            /// - If the predicate is NOT satisfied, it executes the alternative bi-function
            ///
            /// # Parameters
            ///
            /// * `else_function` - The alternative bi-function to execute when predicate fails
            ///
            /// # Returns
            ///
            /// Returns a new bi-function that handles both conditional branches
            ///
            /// # Examples
            ///
            /// ```rust
            /// use qubit_function::{BiFunction, BoxBiFunction};
            ///
            /// let func = BoxBiFunction::new(|x: &i32, y: &i32| x + y);
            /// let alternative = BoxBiFunction::new(|x: &i32, y: &i32| x * y);
            ///
            /// let conditional = func.when(|x: &i32, y: &i32| *x > 0 && *y > 0).or_else(alternative);
            ///
            /// assert_eq!(conditional.apply(&3, &4), 7);   // 3 + 4 = 7 (predicate satisfied)
            /// assert_eq!(conditional.apply(&-2, &4), -8); // -2 * 4 = -8 (predicate failed)
            /// ```
            pub fn or_else<F>(self, else_function: F) -> $box_function_type<$t, $u, $r>
            where
                $t: 'static,
                $u: 'static,
                $r: 'static,
                F: $else_function_trait<$t, $u, $r> + 'static,
            {
                let predicate = self.predicate;
                impl_box_conditional_function!(@let_function $else_function_trait, then_function, self.function);
                impl_box_conditional_function!(@let_function $else_function_trait, else_function, else_function);
                $box_function_type::new(move |t, u| {
                    if predicate.test(t, u) {
                        then_function.apply(t, u)
                    } else {
                        else_function.apply(t, u)
                    }
                })
            }
        }
    };
}

pub(crate) use impl_box_conditional_function;