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 prism3_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.mutate_once(&mut target);
assert_eq!(target, vec![0, 1, 2, 3]);

Method Chaining

use prism3_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.mutate_once(&mut target);
assert_eq!(target, vec![0, 1, 2, 3, 4]);

Author

Haixing Hu

Implementations

impl<T> BoxMutatorOnce<T>

where T: 'static,

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

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

Creates a new BoxMutatorOnce

Parameters

• f - The closure to wrap

Returns

Returns a new BoxMutatorOnce<T> instance

Examples

use prism3_function::{MutatorOnce, BoxMutatorOnce};

let data = String::from("world");
let mutator = BoxMutatorOnce::new(move |x: &mut String| {
    x.push_str(" ");
    x.push_str(&data); // Move data
});

let mut target = String::from("hello");
mutator.mutate_once(&mut target);
assert_eq!(target, "hello world");

Examples found in repository

examples/mutator_once_demo.rs (lines 21-24)

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.mutate_once(&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.mutate_once(&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.mutate_once(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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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/mutator_once_conditional_demo.rs (lines 22-25)

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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(data);
                }
            } else if let Some(callback) = self.on_invalid.take() {
                callback.mutate_once(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 noop() -> Self

Creates a no-op mutator

Returns a mutator that performs no operation.

Returns

Returns a no-op mutator

Examples

use prism3_function::{MutatorOnce, BoxMutatorOnce};

let noop = BoxMutatorOnce::<i32>::noop();
let mut value = 42;
noop.mutate_once(&mut value);
assert_eq!(value, 42); // Value unchanged

pub fn and_then<C>(self, next: C) -> Self

where C: MutatorOnce<T> + 'static,

Chains another mutator in sequence

Returns a new mutator that first executes the current operation, then executes the next operation. Consumes self.

Parameters

• next - The mutator to execute after the current operation. Note: This parameter is passed by value and will transfer ownership. Since BoxMutatorOnce cannot be cloned, the parameter will be consumed. Can be:
  • A closure: |x: &mut T|
  • A BoxMutatorOnce<T>
  • Any type implementing MutatorOnce<T>

Returns

Returns a new composed BoxMutatorOnce<T>

Examples

use prism3_function::{MutatorOnce, BoxMutatorOnce};

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

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

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

Examples found in repository

examples/mutator_once_demo.rs (lines 40-43)

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.mutate_once(&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.mutate_once(&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.mutate_once(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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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/mutator_once_conditional_demo.rs (lines 216-219)

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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(data);
                }
            } else if let Some(callback) = self.on_invalid.take() {
                callback.mutate_once(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 when<P>(self, predicate: P) -> BoxConditionalMutatorOnce<T>

where P: Predicate<T> + 'static,

Creates a conditional mutator

Returns a mutator that only executes when a predicate is satisfied.

Parameters

• predicate - The condition to check. Note: This parameter is passed by value and will transfer ownership. If you need to preserve the original predicate, clone it first (if it implements Clone). Can be:
  • A closure: |x: &T| -> bool
  • A function pointer: fn(&T) -> bool
  • A BoxPredicate<T>
  • An RcPredicate<T>
  • An ArcPredicate<T>
  • Any type implementing Predicate<T>

Returns

Returns BoxConditionalMutatorOnce<T>

Examples

Using a closure

use prism3_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.mutate_once(&mut target);
assert_eq!(target, vec![0, 1, 2, 3]);

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.mutate_once(&mut empty);
assert_eq!(empty, Vec::<i32>::new()); // Unchanged

Preserving predicate with clone

use prism3_function::{MutatorOnce, BoxMutatorOnce, RcPredicate};
use prism3_function::predicate::Predicate;

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

// Clone to preserve original predicate
let conditional = mutator.when(predicate.clone());

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

// Original predicate still usable
assert!(predicate.test(&vec![1, 2]));

Using composed predicate

use prism3_function::{MutatorOnce, BoxMutatorOnce};
use prism3_function::predicate::{Predicate, FnPredicateOps};

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

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

Examples found in repository

examples/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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(&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.mutate_once(data);
                }
            } else if let Some(callback) = self.on_invalid.take() {
                callback.mutate_once(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> MutatorOnce<T> for BoxMutatorOnce<T>

fn mutate_once(self, value: &mut T)

Performs the one-time mutation operation

fn into_box_once(self) -> BoxMutatorOnce<T>

where T: 'static,

Converts to BoxMutatorOnce (consuming)

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

where T: 'static,

Converts to a consuming closure FnOnce(&mut T)