Trait MutatingFunctionOnce 

pub trait MutatingFunctionOnce<T, R> {
    // Required method
    fn apply(self, t: &mut T) -> R;

    // Provided methods
    fn into_box(self) -> BoxMutatingFunctionOnce<T, R>
       where Self: Sized + 'static { ... }
    fn into_fn(self) -> impl FnOnce(&mut T) -> R
       where Self: Sized + 'static { ... }
    fn to_box(&self) -> BoxMutatingFunctionOnce<T, R>
       where Self: Sized + Clone + 'static { ... }
    fn to_fn(&self) -> impl FnOnce(&mut T) -> R
       where Self: Sized + Clone + 'static { ... }
}

MutatingFunctionOnce trait - One-time mutating function interface

It is similar to the FnOnce(&mut T) -> R trait in the standard library.

Defines the core behavior of all one-time mutating function types. Performs operations that consume self, accept a mutable reference, potentially modify it, and return a result.

This trait is automatically implemented by:

• All closures implementing FnOnce(&mut T) -> R
• BoxMutatingFunctionOnce<T, R>

Design Rationale

This trait provides a unified abstraction for one-time mutating function operations. The key difference from MutatingFunction:

• MutatingFunction uses &self, can be called multiple times
• MutatingFunctionOnce uses self, can only be called once

Features

• Unified Interface: All one-time mutating functions share the same apply 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 mutating function type

Examples

Generic Function

use qubit_function::{MutatingFunctionOnce, BoxMutatingFunctionOnce};

fn apply<F: MutatingFunctionOnce<Vec<i32>, usize>>(
    func: F,
    initial: Vec<i32>
) -> (Vec<i32>, usize) {
    let mut val = initial;
    let result = func.apply(&mut val);
    (val, result)
}

let data = vec![1, 2, 3];
let func = BoxMutatingFunctionOnce::new(move |x: &mut Vec<i32>| {
    let old_len = x.len();
    x.extend(data);
    old_len
});
let (vec, old_len) = apply(func, vec![0]);
assert_eq!(vec, vec![0, 1, 2, 3]);
assert_eq!(old_len, 1);

Type Conversion

use qubit_function::MutatingFunctionOnce;

let data = vec![1, 2, 3];
let closure = move |x: &mut Vec<i32>| {
    let old_len = x.len();
    x.extend(data);
    old_len
};
let box_func = closure.into_box();

Required Methods

fn apply(self, t: &mut T) -> R

Performs the one-time mutating function operation

Consumes self and executes an operation on the given mutable reference, potentially modifying it, and returns a result. The operation can only be called once.

Parameters

• `t - A mutable reference to the input value

Returns

The computed result value

Examples

use qubit_function::{MutatingFunctionOnce,
                      BoxMutatingFunctionOnce};

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

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

Provided Methods

fn into_box(self) -> BoxMutatingFunctionOnce<T, R>

where Self: Sized + 'static,

Converts to BoxMutatingFunctionOnce (consuming)

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

Note

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

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

where Self: Sized + 'static,

Converts to a consuming closure FnOnce(&mut T) -> R

Consumes self and returns a closure that, when invoked, calls apply(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(&self) -> BoxMutatingFunctionOnce<T, R>

where Self: Sized + Clone + 'static,

Non-consuming adapter to BoxMutatingFunctionOnce

Creates a BoxMutatingFunctionOnce<T, R> 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 function 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(&self) -> impl FnOnce(&mut T) -> R

where Self: Sized + Clone + 'static,

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

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.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<F, T, R> MutatingFunctionOnce<T, R> for F

where F: FnOnce(&mut T) -> R,

impl<T, R> MutatingFunctionOnce<T, R> for BoxMutatingFunctionOnce<T, R>