Struct BoxMutatorOnce

Source

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

Expand description

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

§Author

Haixing Hu

Implementations§

Source §

impl<T> BoxMutatorOnce<T>
where T: 'static,

Source

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.

Source

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.

Source

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.

Source

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

Gets the name of this mutator.

§Returns

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

Source

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

Sets the name of this mutator.

§Parameters

name - The name to set for this mutator

Source

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.

Source

pub fn when(self, predicate: P) -> BoxConditionalMutatorOnce<T>
where 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 prism3_rust_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

Source

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 prism3_rust_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)