Trait MutatorOnce 

pub trait MutatorOnce<T> {
    // Required method
    fn mutate_once(self, value: &mut T);

    // Provided methods
    fn into_box_once(self) -> BoxMutatorOnce<T>
       where Self: Sized + 'static,
             T: 'static { ... }
    fn into_fn_once(self) -> impl FnOnce(&mut T)
       where Self: Sized + 'static,
             T: 'static { ... }
    fn to_box_once(&self) -> BoxMutatorOnce<T>
       where Self: Sized + Clone + 'static,
             T: 'static { ... }
    fn to_fn_once(&self) -> impl FnOnce(&mut T)
       where Self: Sized + Clone + 'static,
             T: 'static { ... }
}

MutatorOnce trait - One-time mutator interface

Defines the core behavior of all one-time mutator types. Performs operations that consume self and modify the input value.

This trait is automatically implemented by:

• All closures implementing FnOnce(&mut T)
• BoxMutatorOnce<T>

Design Rationale

This trait provides a unified abstraction for one-time mutation operations. The key difference from Mutator:

• Mutator uses &mut self, can be called multiple times
• MutatorOnce uses self, can only be called once

Features

• Unified Interface: All one-time mutators share the same mutate method signature
• Automatic Implementation: Closures automatically implement this trait with zero overhead
• Type Conversions: Provides into_box method for type conversion
• Generic Programming: Write functions that work with any one-time mutator type

Examples

Generic Function

use prism3_function::{MutatorOnce, BoxMutatorOnce};

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

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

Type Conversion

use prism3_function::MutatorOnce;

let data = vec![1, 2, 3];
let closure = move |x: &mut Vec<i32>| x.extend(data);
let box_mutator = closure.into_box_once();

Author

Haixing Hu

Required Methods

fn mutate_once(self, value: &mut T)

Performs the one-time mutation operation

Consumes self and executes an operation on the given mutable reference. The operation typically modifies the input value or produces side effects, and can only be called once.

Parameters

• value - A mutable reference to the value to be mutated

Examples

use prism3_function::{MutatorOnce, BoxMutatorOnce};

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

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

Provided Methods

fn into_box_once(self) -> BoxMutatorOnce<T>

where Self: Sized + 'static, T: 'static,

Converts to BoxMutatorOnce (consuming)

Consumes self and returns an owned BoxMutatorOnce<T>. The default implementation simply wraps the consuming mutate_once(self, &mut T) call in a Box<dyn FnOnce(&mut T)>. Types that can provide a cheaper or identity conversion (for example BoxMutatorOnce itself) should override this method.

Note

• This method consumes the source value.
• Implementors may return self directly when Self is already a BoxMutatorOnce<T> to avoid the extra wrapper allocation.

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

where Self: Sized + 'static, T: 'static,

Converts to a consuming closure FnOnce(&mut T)

Consumes self and returns a closure that, when invoked, calls mutate_once(self, &mut T). This is the default, straightforward implementation; types that can produce a more direct function pointer or avoid additional captures may override it.

fn to_box_once(&self) -> BoxMutatorOnce<T>

where Self: Sized + Clone + 'static, T: 'static,

Non-consuming adapter to BoxMutatorOnce

Creates a BoxMutatorOnce<T> that does not consume self. The default implementation requires Self: Clone and clones the receiver for the stored closure; the clone is consumed when the boxed mutator is invoked. Types that can provide a zero-cost adapter (for example clonable closures) should override this method to avoid unnecessary allocations.

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

where Self: Sized + Clone + 'static, T: 'static,

Non-consuming adapter to a callable FnOnce(&mut T)

Returns a closure that does not consume self. The default requires Self: Clone and clones self for the captured closure; the clone is consumed when the returned closure is invoked. Implementors may provide more efficient adapters for specific types.

Implementors

impl<T> MutatorOnce<T> for ArcMutator<T>

where T: Send + 'static,

impl<T> MutatorOnce<T> for BoxMutator<T>

where T: 'static,

impl<T> MutatorOnce<T> for RcMutator<T>

where T: 'static,

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

where T: 'static,

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

impl<T, F> MutatorOnce<T> for F

where F: FnOnce(&mut T),