Struct BoxMutatorOnce 

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

BoxMutatorOnce struct

A one-time mutator implementation based on Box<dyn FnOnce(&mut T)> for single ownership scenarios. This is the only MutatorOnce implementation type because FnOnce conflicts with shared ownership semantics.

Features

• Single Ownership: Not cloneable, consumes self on use
• Zero Overhead: No reference counting or locking
• Move Semantics: Can capture and move variables
• Method Chaining: Compose multiple operations via and_then

Use Cases

Choose BoxMutatorOnce when:

• Need to store FnOnce closures (with moved captured variables)
• One-time resource transfer operations
• Post-initialization callbacks
• Complex operations requiring ownership transfer

Performance

BoxMutatorOnce performance characteristics:

• No reference counting overhead
• No lock acquisition or runtime borrow checking
• Direct function call through vtable
• Minimal memory footprint (single pointer)

Why No Arc/Rc Variants?

FnOnce can only be called once, which conflicts with Arc/Rc shared ownership semantics:

• Arc/Rc implies multiple owners might need to call
• FnOnce is consumed after calling, cannot be called again
• This semantic incompatibility makes Arc/Rc variants meaningless

Examples

Basic Usage

use qubit_function::{MutatorOnce, BoxMutatorOnce};

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

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

Method Chaining

use qubit_function::{MutatorOnce, BoxMutatorOnce};

let data1 = vec![1, 2];
let data2 = vec![3, 4];

let chained = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
    x.extend(data1);
})
.and_then(move |x: &mut Vec<i32>| {
    x.extend(data2);
});

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

Author

Haixing Hu

Implementations

impl<T> BoxMutatorOnce<T>

pub fn new<F>(f: F) -> Self

where F: FnOnce(&mut T) + 'static,

Creates a new mutator.

Wraps the provided closure in the appropriate smart pointer type for this mutator implementation.

Examples found in repository

examples/mutators/mutator_once_demo.rs (lines 25-28)

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

    // 1. Basic usage: moving captured variables
    println!("1. Basic usage: moving captured variables");
    let data = vec![1, 2, 3];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });

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

    // 2. Method chaining: combining multiple operations
    println!("2. Method chaining: combining multiple operations");
    let prefix = vec![1, 2];
    let middle = vec![3, 4];
    let suffix = vec![5, 6];

    let chained = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding prefix: {:?}", prefix);
        x.extend(prefix);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Adding middle: {:?}", middle);
        x.extend(middle);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Adding suffix: {:?}", suffix);
        x.extend(suffix);
    });

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

    // 3. Initializer pattern
    println!("3. Initializer pattern");

    struct Initializer {
        name: String,
        on_complete: Option<BoxMutatorOnce<Vec<String>>>,
    }

    impl Initializer {
        fn new<F>(name: impl Into<String>, callback: F) -> Self
        where
            F: FnOnce(&mut Vec<String>) + 'static,
        {
            Self {
                name: name.into(),
                on_complete: Some(BoxMutatorOnce::new(callback)),
            }
        }

        fn run(mut self, data: &mut Vec<String>) {
            println!("   Initializer '{}' is running", self.name);
            data.push(format!("Initialized by {}", self.name));

            if let Some(callback) = self.on_complete.take() {
                println!("   Executing completion callback");
                callback.apply(data);
            }
        }
    }

    let extra = vec!["extra1".to_string(), "extra2".to_string()];
    let init = Initializer::new("MainInit", move |values| {
        println!("   Adding extra data in callback: {:?}", extra);
        values.extend(extra);
    });

    let mut config = Vec::new();
    init.run(&mut config);
    println!("   Final config: {:?}\n", config);

    // 4. String builder pattern
    println!("4. String builder pattern");
    let greeting = String::from("Hello, ");
    let name = String::from("Alice");
    let punctuation = String::from("!");

    let builder = BoxMutatorOnce::new(move |s: &mut String| {
        println!("   Adding greeting: {}", greeting);
        s.insert_str(0, &greeting);
    })
    .and_then(move |s: &mut String| {
        println!("   Adding name: {}", name);
        s.push_str(&name);
    })
    .and_then(move |s: &mut String| {
        println!("   Adding punctuation: {}", punctuation);
        s.push_str(&punctuation);
    })
    .and_then(|s: &mut String| {
        println!("   Converting to uppercase");
        *s = s.to_uppercase();
    });

    let mut message = String::new();
    builder.apply(&mut message);
    println!("   Final message: {}\n", message);

    // 5. Direct closure usage
    println!("5. Direct closure usage");
    let data1 = vec![10, 20];
    let data2 = vec![30, 40];

    let chained_closure = (move |x: &mut Vec<i32>| {
        println!("   Step 1: Adding {:?}", data1);
        x.extend(data1);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Step 2: Adding {:?}", data2);
        x.extend(data2);
    })
    .and_then(|x: &mut Vec<i32>| {
        println!("   Step 3: Multiplying each element by 2");
        x.iter_mut().for_each(|n| *n *= 2);
    });

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

    // 6. Resource transfer scenario
    println!("6. Resource transfer scenario");
    let large_data = vec![1; 10];
    println!(
        "   Preparing to transfer large data (length: {})",
        large_data.len()
    );

    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Transferring data (moving, not cloning)");
        x.extend(large_data); // large_data is moved, not cloned
    });

    let mut container = Vec::new();
    mutator.apply(&mut container);
    println!("   Data length in container: {}\n", container.len());

    // 7. Generic function usage
    println!("7. Generic function usage");

    fn apply_transformation<M: MutatorOnce<Vec<i32>>>(mutator: M, initial: Vec<i32>) -> Vec<i32> {
        let mut val = initial;
        mutator.apply(&mut val);
        val
    }

    let data = vec![100, 200, 300];
    let result = apply_transformation(
        move |x: &mut Vec<i32>| {
            println!("   Adding in generic function: {:?}", data);
            x.extend(data);
        },
        vec![0],
    );
    println!("   Result: {:?}\n", result);

    // 8. Configuration builder
    println!("8. Configuration builder");

    struct Config {
        options: Vec<String>,
    }

    impl Config {
        fn new() -> Self {
            Self {
                options: Vec::new(),
            }
        }

        fn with_defaults(mut self) -> Self {
            println!("   Adding default options");
            self.options.push("default1".to_string());
            self.options.push("default2".to_string());
            self
        }

        fn customize<F>(mut self, customizer: F) -> Self
        where
            F: FnOnce(&mut Vec<String>) + 'static,
        {
            println!("   Applying custom configuration");
            customizer.apply(&mut self.options);
            self
        }

        fn build(self) -> Self {
            println!("   Configuration build completed");
            self
        }
    }

    let custom_opts = vec!["custom1".to_string(), "custom2".to_string()];
    let config = Config::new()
        .with_defaults()
        .customize(move |opts| {
            println!("   Adding custom options: {:?}", custom_opts);
            opts.extend(custom_opts);
        })
        .build();

    println!("   Final options: {:?}\n", config.options);

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

examples/mutators/mutator_once_conditional_demo.rs (lines 26-29)

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 new_with_name<F>(name: &str, f: F) -> Self

where F: FnOnce(&mut T) + 'static,

Creates a new named mutator.

Wraps the provided closure and assigns it a name, which is useful for debugging and logging purposes.

pub fn new_with_optional_name<F>(f: F, name: Option<String>) -> Self

where F: FnOnce(&mut T) + 'static,

Creates a new named mutator with an optional name.

Wraps the provided closure and assigns it an optional name.

pub fn name(&self) -> Option<&str>

Gets the name of this mutator.

Returns

Returns Some(&str) if a name was set, None otherwise.

pub fn set_name(&mut self, name: &str)

Sets the name of this mutator.

Parameters

• name - The name to set for this mutator

pub fn clear_name(&mut self)

Clears the name of this mutator.

pub fn noop() -> Self

Creates a no-operation mutator.

Creates a mutator that does nothing when called. Useful for default values or placeholder implementations.

Returns

Returns a new mutator instance that performs no operation.

pub fn when<P>(self, predicate: P) -> BoxConditionalMutatorOnce<T>

where T: 'static, P: Predicate<T> + 'static,

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

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

Examples found in repository

examples/mutators/mutator_once_conditional_demo.rs (lines 30-33)

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 and_then<M>(self, after: M) -> BoxMutatorOnce<T>

where Self: Sized + 'static, T: 'static, M: MutatorOnce<T> + 'static,

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

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)

Examples found in repository

examples/mutators/mutator_once_demo.rs (lines 44-47)

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

    // 1. Basic usage: moving captured variables
    println!("1. Basic usage: moving captured variables");
    let data = vec![1, 2, 3];
    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding data: {:?}", data);
        x.extend(data);
    });

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

    // 2. Method chaining: combining multiple operations
    println!("2. Method chaining: combining multiple operations");
    let prefix = vec![1, 2];
    let middle = vec![3, 4];
    let suffix = vec![5, 6];

    let chained = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Adding prefix: {:?}", prefix);
        x.extend(prefix);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Adding middle: {:?}", middle);
        x.extend(middle);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Adding suffix: {:?}", suffix);
        x.extend(suffix);
    });

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

    // 3. Initializer pattern
    println!("3. Initializer pattern");

    struct Initializer {
        name: String,
        on_complete: Option<BoxMutatorOnce<Vec<String>>>,
    }

    impl Initializer {
        fn new<F>(name: impl Into<String>, callback: F) -> Self
        where
            F: FnOnce(&mut Vec<String>) + 'static,
        {
            Self {
                name: name.into(),
                on_complete: Some(BoxMutatorOnce::new(callback)),
            }
        }

        fn run(mut self, data: &mut Vec<String>) {
            println!("   Initializer '{}' is running", self.name);
            data.push(format!("Initialized by {}", self.name));

            if let Some(callback) = self.on_complete.take() {
                println!("   Executing completion callback");
                callback.apply(data);
            }
        }
    }

    let extra = vec!["extra1".to_string(), "extra2".to_string()];
    let init = Initializer::new("MainInit", move |values| {
        println!("   Adding extra data in callback: {:?}", extra);
        values.extend(extra);
    });

    let mut config = Vec::new();
    init.run(&mut config);
    println!("   Final config: {:?}\n", config);

    // 4. String builder pattern
    println!("4. String builder pattern");
    let greeting = String::from("Hello, ");
    let name = String::from("Alice");
    let punctuation = String::from("!");

    let builder = BoxMutatorOnce::new(move |s: &mut String| {
        println!("   Adding greeting: {}", greeting);
        s.insert_str(0, &greeting);
    })
    .and_then(move |s: &mut String| {
        println!("   Adding name: {}", name);
        s.push_str(&name);
    })
    .and_then(move |s: &mut String| {
        println!("   Adding punctuation: {}", punctuation);
        s.push_str(&punctuation);
    })
    .and_then(|s: &mut String| {
        println!("   Converting to uppercase");
        *s = s.to_uppercase();
    });

    let mut message = String::new();
    builder.apply(&mut message);
    println!("   Final message: {}\n", message);

    // 5. Direct closure usage
    println!("5. Direct closure usage");
    let data1 = vec![10, 20];
    let data2 = vec![30, 40];

    let chained_closure = (move |x: &mut Vec<i32>| {
        println!("   Step 1: Adding {:?}", data1);
        x.extend(data1);
    })
    .and_then(move |x: &mut Vec<i32>| {
        println!("   Step 2: Adding {:?}", data2);
        x.extend(data2);
    })
    .and_then(|x: &mut Vec<i32>| {
        println!("   Step 3: Multiplying each element by 2");
        x.iter_mut().for_each(|n| *n *= 2);
    });

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

    // 6. Resource transfer scenario
    println!("6. Resource transfer scenario");
    let large_data = vec![1; 10];
    println!(
        "   Preparing to transfer large data (length: {})",
        large_data.len()
    );

    let mutator = BoxMutatorOnce::new(move |x: &mut Vec<i32>| {
        println!("   Transferring data (moving, not cloning)");
        x.extend(large_data); // large_data is moved, not cloned
    });

    let mut container = Vec::new();
    mutator.apply(&mut container);
    println!("   Data length in container: {}\n", container.len());

    // 7. Generic function usage
    println!("7. Generic function usage");

    fn apply_transformation<M: MutatorOnce<Vec<i32>>>(mutator: M, initial: Vec<i32>) -> Vec<i32> {
        let mut val = initial;
        mutator.apply(&mut val);
        val
    }

    let data = vec![100, 200, 300];
    let result = apply_transformation(
        move |x: &mut Vec<i32>| {
            println!("   Adding in generic function: {:?}", data);
            x.extend(data);
        },
        vec![0],
    );
    println!("   Result: {:?}\n", result);

    // 8. Configuration builder
    println!("8. Configuration builder");

    struct Config {
        options: Vec<String>,
    }

    impl Config {
        fn new() -> Self {
            Self {
                options: Vec::new(),
            }
        }

        fn with_defaults(mut self) -> Self {
            println!("   Adding default options");
            self.options.push("default1".to_string());
            self.options.push("default2".to_string());
            self
        }

        fn customize<F>(mut self, customizer: F) -> Self
        where
            F: FnOnce(&mut Vec<String>) + 'static,
        {
            println!("   Applying custom configuration");
            customizer.apply(&mut self.options);
            self
        }

        fn build(self) -> Self {
            println!("   Configuration build completed");
            self
        }
    }

    let custom_opts = vec!["custom1".to_string(), "custom2".to_string()];
    let config = Config::new()
        .with_defaults()
        .customize(move |opts| {
            println!("   Adding custom options: {:?}", custom_opts);
            opts.extend(custom_opts);
        })
        .build();

    println!("   Final options: {:?}\n", config.options);

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

examples/mutators/mutator_once_conditional_demo.rs (lines 220-223)

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 BoxMutatorOnce<T>

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

Formats the value using the given formatter.

impl<T> Display for BoxMutatorOnce<T>

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

Formats the value using the given formatter.

impl<T> MutatorOnce<T> for BoxMutatorOnce<T>

fn apply(self, value: &mut T)

Performs the one-time mutation operation

fn into_box(self) -> BoxMutatorOnce<T>

Converts to BoxMutatorOnce (consuming)

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

Converts to a consuming closure FnOnce(&mut T)