Struct BoxConditionalMutator 

pub struct BoxConditionalMutator<T> { /* private fields */ }

BoxConditionalMutator struct

A conditional mutator that only executes when a predicate is satisfied. Uses BoxMutator and BoxPredicate for single ownership semantics.

This type is typically created by calling BoxMutator::when() and is designed to work with the or_else() method to create if-then-else logic.

Features

• Single Ownership: Not cloneable, consumes self on use
• Conditional Execution: Only mutates when predicate returns true
• Chainable: Can add or_else branch to create if-then-else logic
• Implements Mutator: Can be used anywhere a Mutator is expected

Examples

Basic Conditional Execution

use qubit_function::{Mutator, BoxMutator};

let mutator = BoxMutator::new(|x: &mut i32| *x *= 2);
let mut conditional = mutator.when(|x: &i32| *x > 0);

let mut positive = 5;
conditional.apply(&mut positive);
assert_eq!(positive, 10); // Executed

let mut negative = -5;
conditional.apply(&mut negative);
assert_eq!(negative, -5); // Not executed

With or_else Branch

use qubit_function::{Mutator, BoxMutator};

let mut mutator = BoxMutator::new(|x: &mut i32| *x *= 2)
    .when(|x: &i32| *x > 0)
    .or_else(|x: &mut i32| *x -= 1);

let mut positive = 5;
mutator.apply(&mut positive);
assert_eq!(positive, 10); // when branch executed

let mut negative = -5;
mutator.apply(&mut negative);
assert_eq!(negative, -6); // or_else branch executed

Author

Haixing Hu

Implementations

impl<T> BoxConditionalMutator<T>

pub fn and_then<M>(self, next: M) -> BoxMutator<T>

where T: 'static, M: Mutator<T> + 'static,

Chains another mutator in sequence

Combines the current conditional mutator with another mutator into a new mutator that implements the following semantics:

When the returned mutator is called with an argument:

1. First, it checks the predicate of this conditional mutator
2. If the predicate is satisfied, it executes the internal mutator of this conditional mutator
3. Then, regardless of whether the predicate was satisfied, it unconditionally executes the next mutator

In other words, this creates a mutator that conditionally executes the first action (based on the predicate), and then always executes the second action.

Parameters

• next - The next mutator to execute (always executed)

Returns

Returns a new combined mutator

Examples

// use std::sync::atomic::{AtomicI32, Ordering};
//
// let result = AtomicI32::new(0);
//
// let mutator1 = BoxMutator::new(|x: &mut i32| {
//     *x += 1;
// });
//
// let mutator2 = BoxMutator::new(|x: &mut i32| {
//     *x += 2;
// });
//
// let conditional = mutator1.when(|x| *x > 0);
// let chained = conditional.and_then(mutator2);
//
// let mut val = 5;
// chained.apply(&mut val);  // val = 5 + 1 + 2 = 8
// let mut val2 = -1;
// chained.apply(&mut val2); // val2 = -1 + 2 = 1 (not -1 + 1 + 2!)
// ```

pub fn or_else<M>(self, else_mutator: M) -> BoxMutator<T>

where T: 'static, M: Mutator<T> + 'static,

Adds an else branch

Executes the original mutator when the condition is satisfied, otherwise executes else_mutator.

Parameters

• else_mutator - The mutator for the else branch

Returns

Returns a new mutator with if-then-else logic

Examples found in repository

examples/mutators/mutator_demo.rs (line 115)

fn main() {
    println!("=== Mutator Demo ===\n");

    // ========================================================================
    // Example 1: BoxMutator Basic Usage
    // ========================================================================
    println!("Example 1: BoxMutator Basic Usage");
    println!("{}", "-".repeat(50));

    let mutator = BoxMutator::new(|x: &mut i32| {
        *x *= 2;
    });
    let mut value = 5;
    println!("Initial value: {}", value);
    mutator.apply(&mut value);
    println!("After BoxMutator execution: {}\n", value);

    // ========================================================================
    // Example 2: BoxMutator Method Chaining
    // ========================================================================
    println!("Example 2: BoxMutator Method Chaining");
    println!("{}", "-".repeat(50));

    let chained = BoxMutator::new(|x: &mut i32| {
        *x *= 2; // multiply by 2
    })
    .and_then(|x: &mut i32| {
        *x += 10; // add 10
    })
    .and_then(|x: &mut i32| {
        *x = *x * *x; // square
    });

    let mut value = 5;
    println!("Initial value: {}", value);
    chained.apply(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20, 20 * 20 = 400)\n", value);

    // ========================================================================
    // Example 3: Closure Extension Methods
    // ========================================================================
    println!("Example 3: Direct Use of Closure Extension Methods");
    println!("{}", "-".repeat(50));

    let closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.apply(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20)\n", value);

    // ========================================================================
    // Example 4: BoxMutator Factory Methods
    // ========================================================================
    println!("Example 4: BoxMutator Factory Methods");
    println!("{}", "-".repeat(50));

    // noop
    let noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.apply(&mut value);
    println!("After noop: {} (unchanged)\n", value);

    // ========================================================================
    // Example 5: Conditional Mutator
    // ========================================================================
    println!("Example 5: Conditional Mutator");
    println!("{}", "-".repeat(50));

    // when (conditional execution)
    let increment_if_positive = BoxMutator::new(|x: &mut i32| *x += 1).when(|x: &i32| *x > 0);

    let mut positive = 5;
    let mut negative = -5;
    println!(
        "Before when - positive: {}, negative: {}",
        positive, negative
    );
    increment_if_positive.apply(&mut positive);
    increment_if_positive.apply(&mut negative);
    println!(
        "After when - positive: {}, negative: {}\n",
        positive, negative
    );

    // when().or_else() (conditional branching)
    let adjust = BoxMutator::new(|x: &mut i32| *x *= 2)
        .when(|x: &i32| *x > 0)
        .or_else(|x: &mut i32| *x = -*x);

    let mut positive = 10;
    let mut negative = -10;
    println!(
        "Before when().or_else() - positive: {}, negative: {}",
        positive, negative
    );
    adjust.apply(&mut positive);
    adjust.apply(&mut negative);
    println!(
        "After when().or_else() - positive: {}, negative: {}\n",
        positive, negative
    );

    // ========================================================================
    // Example 6: ArcMutator - Multi-threaded Sharing
    // ========================================================================
    println!("Example 6: ArcMutator - Multi-threaded Sharing");
    println!("{}", "-".repeat(50));

    let shared = ArcMutator::new(|x: &mut i32| *x *= 2);

    // Clone for another thread
    let shared_clone = shared.clone();
    let handle = thread::spawn(move || {
        let mut value = 5;
        let mutator = shared_clone;
        mutator.apply(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

    // Use in main thread
    let mut value = 3;
    let mutator = shared;
    mutator.apply(&mut value);
    println!("Main thread: 3 * 2 = {}", value);

    let thread_result = handle.join().unwrap();
    println!("Thread result: {}\n", thread_result);

    // ========================================================================
    // Example 7: ArcMutator Composition (without consuming original mutator)
    // ========================================================================
    println!("Example 7: ArcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = ArcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = ArcMutator::new(|x: &mut i32| *x += 10);

    // Composition doesn't consume the original mutator
    let pipeline1 = double.and_then(add_ten.clone());
    let pipeline2 = add_ten.and_then(double.clone());

    let mut value1 = 5;
    let p1 = pipeline1;
    p1.apply(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let p2 = pipeline2;
    p2.apply(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}", value2);

    // double and add_ten are still available
    let mut value3 = 10;
    let d = double;
    d.apply(&mut value3);
    println!("Original double still available: 10 -> {}\n", value3);

    // ========================================================================
    // Example 8: RcMutator - Single-threaded Sharing
    // ========================================================================
    println!("Example 8: RcMutator - Single-threaded Sharing");
    println!("{}", "-".repeat(50));

    let rc_mutator = RcMutator::new(|x: &mut i32| *x *= 2);

    // Clone multiple copies
    let clone1 = rc_mutator.clone();
    let clone2 = rc_mutator.clone();

    let mut value1 = 5;
    let c1 = clone1;
    c1.apply(&mut value1);
    println!("clone1: 5 -> {}", value1);

    let mut value2 = 3;
    let c2 = clone2;
    c2.apply(&mut value2);
    println!("clone2: 3 -> {}", value2);

    let mut value3 = 7;
    let c3 = rc_mutator;
    c3.apply(&mut value3);
    println!("Original: 7 -> {}\n", value3);

    // ========================================================================
    // Example 9: RcMutator Composition (borrowing &self)
    // ========================================================================
    println!("Example 9: RcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = RcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = RcMutator::new(|x: &mut i32| *x += 10);

    let pipeline1 = double.and_then(add_ten.clone());
    let pipeline2 = add_ten.and_then(double.clone());

    let mut value1 = 5;
    let p1 = pipeline1;
    p1.apply(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let p2 = pipeline2;
    p2.apply(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}\n", value2);

    // ========================================================================
    // Example 10: Unified Mutator trait
    // ========================================================================
    println!("Example 10: Unified Mutator trait");
    println!("{}", "-".repeat(50));

    fn apply_to_all<M: Mutator<i32>>(mutator: &mut M, values: &mut [i32]) {
        for value in values.iter_mut() {
            mutator.apply(value);
        }
    }

    let mut values1 = vec![1, 2, 3, 4, 5];
    let mut box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    println!("Using BoxMutator: {:?}", values1);
    apply_to_all(&mut box_mut, &mut values1);
    println!("Result: {:?}", values1);

    let mut values2 = vec![1, 2, 3, 4, 5];
    let mut arc_mut = ArcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using ArcMutator: {:?}", values2);
    apply_to_all(&mut arc_mut, &mut values2);
    println!("Result: {:?}", values2);

    let mut values3 = vec![1, 2, 3, 4, 5];
    let mut rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using RcMutator: {:?}", values3);
    apply_to_all(&mut rc_mut, &mut values3);
    println!("Result: {:?}", values3);

    let mut values4 = vec![1, 2, 3, 4, 5];
    let mut closure = |x: &mut i32| *x *= 2;
    println!("Using closure: {:?}", values4);
    apply_to_all(&mut closure, &mut values4);
    println!("Result: {:?}\n", values4);

    // ========================================================================
    // Example 11: Complex Data Processing Pipeline
    // ========================================================================
    println!("Example 11: Complex Data Processing Pipeline");
    println!("{}", "-".repeat(50));

    let pipeline = BoxMutator::new(|x: &mut i32| {
        // Validation: clamp to 0-100
        *x = (*x).clamp(0, 100);
    })
    .and_then(|x: &mut i32| {
        // Normalization: scale to 0-10
        *x /= 10;
    })
    .and_then(|x: &mut i32| {
        // Transformation: square
        *x = *x * *x;
    });

    let mut value1 = -50;
    pipeline.apply(&mut value1);
    println!("-50 -> {}", value1);

    let mut value2 = 200;
    pipeline.apply(&mut value2);
    println!("200 -> {}", value2);

    let mut value3 = 30;
    pipeline.apply(&mut value3);
    println!("30 -> {}\n", value3);

    // ========================================================================
    // Example 12: String Processing
    // ========================================================================
    println!("Example 12: String Processing");
    println!("{}", "-".repeat(50));

    let string_processor = BoxMutator::new(|s: &mut String| s.retain(|c| !c.is_whitespace()))
        .and_then(|s: &mut String| *s = s.to_lowercase())
        .and_then(|s: &mut String| s.push_str("!!!"));

    let mut text = String::from("Hello World");
    println!("Original: {}", text);
    string_processor.apply(&mut text);
    println!("After processing: {}\n", text);

    // ========================================================================
    // Example 13: Type Conversion
    // ========================================================================
    println!("Example 13: Type Conversion");
    println!("{}", "-".repeat(50));

    // Closure -> BoxMutator
    let closure = |x: &mut i32| *x *= 2;
    let box_mut = closure.into_box();
    let mut value = 5;
    box_mut.apply(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

    // Closure -> RcMutator
    let closure = |x: &mut i32| *x *= 2;
    let rc_mut = closure.into_rc();
    let mut value = 5;
    rc_mut.apply(&mut value);
    println!("Closure -> RcMutator: 5 -> {}", value);

    // Closure -> ArcMutator
    let closure = |x: &mut i32| *x *= 2;
    let arc_mut = closure.into_arc();
    let mut value = 5;
    arc_mut.apply(&mut value);
    println!("Closure -> ArcMutator: 5 -> {}", value);

    // BoxMutator -> RcMutator
    let box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    let rc_mut = box_mut.into_rc();
    let mut value = 5;
    rc_mut.apply(&mut value);
    println!("BoxMutator -> RcMutator: 5 -> {}", value);

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.apply(&mut value);
    println!("RcMutator -> BoxMutator: 5 -> {}\n", value);

    // ========================================================================
    // Example 14: Custom Types
    // ========================================================================
    println!("Example 14: Custom Types");
    println!("{}", "-".repeat(50));

    #[derive(Debug, Clone)]
    struct Point {
        x: i32,
        y: i32,
    }

    let processor = BoxMutator::new(|p: &mut Point| p.x *= 2)
        .and_then(|p: &mut Point| p.y *= 2)
        .and_then(|p: &mut Point| p.x += p.y);

    let mut point = Point { x: 3, y: 4 };
    println!("Original point: {:?}", point);
    processor.apply(&mut point);
    println!("After processing: {:?}\n", point);

    println!("=== All Examples Completed ===");
}

Trait Implementations

impl<T> Debug for BoxConditionalMutator<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Display for BoxConditionalMutator<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Mutator<T> for BoxConditionalMutator<T>

fn apply(&self, value: &mut T)

Performs the stateless mutation operation

fn into_box(self) -> BoxMutator<T>

where Self: 'static,

Convert this mutator into a BoxMutator<T>.

fn into_rc(self) -> RcMutator<T>

where Self: 'static,

Convert this mutator into an RcMutator<T>.

fn into_fn(self) -> impl Fn(&mut T)

Consume the mutator and return an Fn(&mut T) closure.

fn into_arc(self) -> ArcMutator<T>

where Self: Sized + Send + Sync + 'static,

Convert this mutator into an ArcMutator<T>.

fn into_once(self) -> BoxMutatorOnce<T>

where Self: Sized + 'static,

Convert this mutator into a BoxMutatorOnce<T> (consuming).