Struct BoxConditionalMutatorOnce 

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

BoxConditionalMutatorOnce struct

A conditional one-time mutator that only executes when a predicate is satisfied. Uses BoxMutatorOnce and BoxPredicate for single ownership semantics.

This type is typically created by calling BoxMutatorOnce::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 MutatorOnce: Can be used anywhere a MutatorOnce is expected

Examples

Basic Conditional Execution

use qubit_function::{MutatorOnce, BoxMutatorOnce};

let data = vec![1, 2, 3];
let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
    x.extend(data);
});
let conditional = mutator.when(|x: &Vec<i32>| !x.is_empty());

let mut target = vec![0];
conditional.apply(&mut target);
assert_eq!(target, vec![0, 1, 2, 3]); // Executed

let mut empty = Vec::new();
let data2 = vec![4, 5];
let mutator2 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
    x.extend(data2);
});
let conditional2 = mutator2.when(|x: &Vec<i32>| x.len() > 5);
conditional2.apply(&mut empty);
assert_eq!(empty, Vec::<i32>::new()); // Not executed

With or_else Branch

use qubit_function::{MutatorOnce, BoxMutatorOnce};

let data1 = vec![1, 2, 3];
let data2 = vec![99];
let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
    x.extend(data1);
})
.when(|x: &Vec<i32>| !x.is_empty())
.or_else(move |x: &mut Vec<i32>| {
    x.extend(data2);
});

let mut target = vec![0];
mutator.apply(&mut target);
assert_eq!(target, vec![0, 1, 2, 3]); // when branch executed

let data3 = vec![4, 5];
let data4 = vec![99];
let mutator2 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
    x.extend(data3);
})
.when(|x: &Vec<i32>| x.is_empty())
.or_else(move |x: &mut Vec<i32>| {
    x.extend(data4);
});

let mut target2 = vec![0];
mutator2.apply(&mut target2);
assert_eq!(target2, vec![0, 99]); // or_else branch executed

Author

Haixing Hu

Implementations

impl<T> BoxConditionalMutatorOnce<T>

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

where T: 'static, M: MutatorOnce<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!)
// ```

Examples found in repository

examples/mutators/mutator_once_conditional_demo.rs (line 195)

fn main() {
    println!("=== MutatorOnce Conditional Execution Examples ===\n");

    // 1. Basic conditional execution - when condition is satisfied
    println!("1. Basic conditional execution - when condition is satisfied");
    let data = vec![1, 2, 3];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Extending vector with data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(|x: &Vec<i32>| {
        println!("   Checking condition: !x.is_empty()");
        !x.is_empty()
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 2. Conditional execution - when condition is not satisfied
    println!("2. Conditional execution - when condition is not satisfied");
    let data = vec![4, 5, 6];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   This should not be executed");
        x.extend(data);
    });
    let conditional = mutator.when(|x: &Vec<i32>| {
        println!("   Checking condition: x.len() > 10");
        x.len() > 10
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?} (unchanged)\n", target);

    // 3. Using BoxPredicate
    println!("3. Using BoxPredicate");
    let pred = BoxPredicate::new(|x: &Vec<i32>| {
        println!("   Predicate: checking if vector is not empty");
        !x.is_empty()
    });
    let data = vec![7, 8, 9];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(pred);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 4. Using composed predicate
    println!("4. Using composed predicate");
    let pred = (|x: &Vec<i32>| {
        println!("   Condition 1: !x.is_empty()");
        !x.is_empty()
    })
    .and(|x: &Vec<i32>| {
        println!("   Condition 2: x.len() < 10");
        x.len() < 10
    });
    let data = vec![10, 11, 12];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(pred);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 5. If-then-else with or_else - when branch
    println!("5. If-then-else with or_else - when branch");
    let data1 = vec![1, 2, 3];
    let data2 = vec![99];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: !x.is_empty()");
        !x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 6. If-then-else with or_else - else branch
    println!("6. If-then-else with or_else - else branch");
    let data1 = vec![4, 5, 6];
    let data2 = vec![99];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: x.is_empty()");
        x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 7. Conditional with integers
    println!("7. Conditional with integers");
    let mutator = BoxMutatorOnce::new(|x: &mut i32| {
        println!("   Multiplying by 2");
        *x *= 2;
    })
    .when(|x: &i32| {
        println!("   Checking: *x > 0");
        *x > 0
    });

    let mut positive = 5;
    println!("   Initial (positive): {}", positive);
    mutator.apply(&mut positive);
    println!("   Result: {}\n", positive);

    // 8. Conditional with integers - not executed
    println!("8. Conditional with integers - not executed");
    let mutator = BoxMutatorOnce::new(|x: &mut i32| {
        println!("   This should not be executed");
        *x *= 2;
    })
    .when(|x: &i32| {
        println!("   Checking: *x > 0");
        *x > 0
    });

    let mut negative = -5;
    println!("   Initial (negative): {}", negative);
    mutator.apply(&mut negative);
    println!("   Result: {} (unchanged)\n", negative);

    // 9. Chaining conditional mutators
    println!("9. Chaining conditional mutators");
    let data1 = vec![1, 2];
    let cond1 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   First mutator: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   First condition: !x.is_empty()");
        !x.is_empty()
    });

    let data2 = vec![3, 4];
    let cond2 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Second mutator: adding {:?}", data2);
        x.extend(data2);
    })
    .when(|x: &Vec<i32>| {
        println!("   Second condition: x.len() < 10");
        x.len() < 10
    });

    let chained = cond1.and_then(cond2);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    chained.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 10. Complex conditional chain
    println!("10. Complex conditional chain");
    let data1 = vec![1, 2];
    let data2 = vec![99];
    let data3 = vec![5, 6];

    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: !x.is_empty()");
        !x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Final step: adding {:?}", data3);
        x.extend(data3);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 11. Real-world scenario: data validation and processing
    println!("11. Real-world scenario: data validation and processing");

    struct DataProcessor {
        on_valid: Option<BoxMutatorOnce<Vec<String>>>,
        on_invalid: Option<BoxMutatorOnce<Vec<String>>>,
    }

    impl DataProcessor {
        fn new<V, I>(on_valid: V, on_invalid: I) -> Self
        where
            V: FnOnce(&mut Vec<String>) + 'static,
            I: FnOnce(&mut Vec<String>) + 'static,
        {
            Self {
                on_valid: Some(BoxMutatorOnce::new(on_valid)),
                on_invalid: Some(BoxMutatorOnce::new(on_invalid)),
            }
        }

        fn process(mut self, data: &mut Vec<String>) {
            let is_valid = !data.is_empty() && data.iter().all(|s| !s.is_empty());
            println!(
                "   Data validation: {}",
                if is_valid { "VALID" } else { "INVALID" }
            );

            if is_valid {
                if let Some(callback) = self.on_valid.take() {
                    callback.apply(data);
                }
            } else if let Some(callback) = self.on_invalid.take() {
                callback.apply(data);
            }
        }
    }

    let valid_suffix = vec!["processed".to_string()];
    let invalid_marker = vec!["[INVALID]".to_string()];

    let processor = DataProcessor::new(
        move |data| {
            println!("   Valid data callback: adding suffix");
            data.extend(valid_suffix);
        },
        move |data| {
            println!("   Invalid data callback: adding error marker");
            data.clear();
            data.extend(invalid_marker);
        },
    );

    let mut valid_data = vec!["item1".to_string(), "item2".to_string()];
    println!("   Processing valid data: {:?}", valid_data);
    processor.process(&mut valid_data);
    println!("   Result: {:?}\n", valid_data);

    println!("=== Examples completed ===");
}

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

where T: 'static, M: MutatorOnce<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_once_conditional_demo.rs (lines 109-112)

fn main() {
    println!("=== MutatorOnce Conditional Execution Examples ===\n");

    // 1. Basic conditional execution - when condition is satisfied
    println!("1. Basic conditional execution - when condition is satisfied");
    let data = vec![1, 2, 3];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Extending vector with data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(|x: &Vec<i32>| {
        println!("   Checking condition: !x.is_empty()");
        !x.is_empty()
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 2. Conditional execution - when condition is not satisfied
    println!("2. Conditional execution - when condition is not satisfied");
    let data = vec![4, 5, 6];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   This should not be executed");
        x.extend(data);
    });
    let conditional = mutator.when(|x: &Vec<i32>| {
        println!("   Checking condition: x.len() > 10");
        x.len() > 10
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?} (unchanged)\n", target);

    // 3. Using BoxPredicate
    println!("3. Using BoxPredicate");
    let pred = BoxPredicate::new(|x: &Vec<i32>| {
        println!("   Predicate: checking if vector is not empty");
        !x.is_empty()
    });
    let data = vec![7, 8, 9];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(pred);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 4. Using composed predicate
    println!("4. Using composed predicate");
    let pred = (|x: &Vec<i32>| {
        println!("   Condition 1: !x.is_empty()");
        !x.is_empty()
    })
    .and(|x: &Vec<i32>| {
        println!("   Condition 2: x.len() < 10");
        x.len() < 10
    });
    let data = vec![10, 11, 12];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });
    let conditional = mutator.when(pred);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    conditional.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 5. If-then-else with or_else - when branch
    println!("5. If-then-else with or_else - when branch");
    let data1 = vec![1, 2, 3];
    let data2 = vec![99];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: !x.is_empty()");
        !x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 6. If-then-else with or_else - else branch
    println!("6. If-then-else with or_else - else branch");
    let data1 = vec![4, 5, 6];
    let data2 = vec![99];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: x.is_empty()");
        x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 7. Conditional with integers
    println!("7. Conditional with integers");
    let mutator = BoxMutatorOnce::new(|x: &mut i32| {
        println!("   Multiplying by 2");
        *x *= 2;
    })
    .when(|x: &i32| {
        println!("   Checking: *x > 0");
        *x > 0
    });

    let mut positive = 5;
    println!("   Initial (positive): {}", positive);
    mutator.apply(&mut positive);
    println!("   Result: {}\n", positive);

    // 8. Conditional with integers - not executed
    println!("8. Conditional with integers - not executed");
    let mutator = BoxMutatorOnce::new(|x: &mut i32| {
        println!("   This should not be executed");
        *x *= 2;
    })
    .when(|x: &i32| {
        println!("   Checking: *x > 0");
        *x > 0
    });

    let mut negative = -5;
    println!("   Initial (negative): {}", negative);
    mutator.apply(&mut negative);
    println!("   Result: {} (unchanged)\n", negative);

    // 9. Chaining conditional mutators
    println!("9. Chaining conditional mutators");
    let data1 = vec![1, 2];
    let cond1 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   First mutator: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   First condition: !x.is_empty()");
        !x.is_empty()
    });

    let data2 = vec![3, 4];
    let cond2 = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Second mutator: adding {:?}", data2);
        x.extend(data2);
    })
    .when(|x: &Vec<i32>| {
        println!("   Second condition: x.len() < 10");
        x.len() < 10
    });

    let chained = cond1.and_then(cond2);

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    chained.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 10. Complex conditional chain
    println!("10. Complex conditional chain");
    let data1 = vec![1, 2];
    let data2 = vec![99];
    let data3 = vec![5, 6];

    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   When branch: adding {:?}", data1);
        x.extend(data1);
    })
    .when(|x: &Vec<i32>| {
        println!("   Checking: !x.is_empty()");
        !x.is_empty()
    })
    .or_else(move |x: &mut Vec<i32>| {
        println!("   Else branch: adding {:?}", data2);
        x.extend(data2);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Final step: adding {:?}", data3);
        x.extend(data3);
    });

    let mut target = vec![0];
    println!("   Initial: {:?}", target);
    mutator.apply(&mut target);
    println!("   Result: {:?}\n", target);

    // 11. Real-world scenario: data validation and processing
    println!("11. Real-world scenario: data validation and processing");

    struct DataProcessor {
        on_valid: Option<BoxMutatorOnce<Vec<String>>>,
        on_invalid: Option<BoxMutatorOnce<Vec<String>>>,
    }

    impl DataProcessor {
        fn new<V, I>(on_valid: V, on_invalid: I) -> Self
        where
            V: FnOnce(&mut Vec<String>) + 'static,
            I: FnOnce(&mut Vec<String>) + 'static,
        {
            Self {
                on_valid: Some(BoxMutatorOnce::new(on_valid)),
                on_invalid: Some(BoxMutatorOnce::new(on_invalid)),
            }
        }

        fn process(mut self, data: &mut Vec<String>) {
            let is_valid = !data.is_empty() && data.iter().all(|s| !s.is_empty());
            println!(
                "   Data validation: {}",
                if is_valid { "VALID" } else { "INVALID" }
            );

            if is_valid {
                if let Some(callback) = self.on_valid.take() {
                    callback.apply(data);
                }
            } else if let Some(callback) = self.on_invalid.take() {
                callback.apply(data);
            }
        }
    }

    let valid_suffix = vec!["processed".to_string()];
    let invalid_marker = vec!["[INVALID]".to_string()];

    let processor = DataProcessor::new(
        move |data| {
            println!("   Valid data callback: adding suffix");
            data.extend(valid_suffix);
        },
        move |data| {
            println!("   Invalid data callback: adding error marker");
            data.clear();
            data.extend(invalid_marker);
        },
    );

    let mut valid_data = vec!["item1".to_string(), "item2".to_string()];
    println!("   Processing valid data: {:?}", valid_data);
    processor.process(&mut valid_data);
    println!("   Result: {:?}\n", valid_data);

    println!("=== Examples completed ===");
}

Trait Implementations

impl<T> Debug for BoxConditionalMutatorOnce<T>

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

Formats the value using the given formatter.

impl<T> Display for BoxConditionalMutatorOnce<T>

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

Formats the value using the given formatter.

impl<T> MutatorOnce<T> for BoxConditionalMutatorOnce<T>

fn apply(self, value: &mut T)

Performs the one-time mutation operation

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

Converts to a consuming closure FnOnce(&mut T)

fn into_box(self) -> BoxMutatorOnce<T>

where Self: Sized + 'static,

Converts to BoxMutatorOnce (consuming)