prism3_function::functions::mutating_function_once

Struct BoxMutatingFunctionOnce

pub struct BoxMutatingFunctionOnce<T, R> { /* private fields */ }

Expand description

BoxMutatingFunctionOnce struct

A one-time mutating function implementation based on Box<dyn FnOnce(&mut T) -> R> for single ownership scenarios. This is the only MutatingFunctionOnce 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
Returns Results: Unlike MutatorOnce, returns information

§Use Cases

Choose BoxMutatingFunctionOnce when:

Need to store FnOnce closures (with moved captured variables)
One-time resource transfer operations with results
Post-initialization callbacks that return status
Complex operations requiring ownership transfer and results

§Performance

BoxMutatingFunctionOnce 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::{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); // Move 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]);

§Method Chaining

use prism3_function::{MutatingFunctionOnce, BoxMutatingFunctionOnce};

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

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

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

§Author

Haixing Hu

Implementations§

Source §

impl<T, R> BoxMutatingFunctionOnce<T, R>
where T: 'static, R: 'static,

Source

pub fn new<F>(f: F) -> Self
where F: FnOnce(&mut T) -> R + 'static,

Creates a new function.

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

Source

pub fn new_with_name<F>(name: &str, f: F) -> Self
where F: FnOnce(&mut T) -> R + 'static,

Creates a new named function.

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) -> R + 'static,

Creates a new named function 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 function.

§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 function.

§Parameters

name - The name to set for this function

Source

pub fn when(self, predicate: P) -> BoxConditionalMutatingFunctionOnce<T, R>
where P: Predicate<T> + 'static,

Creates a conditional function that executes based on predicate result.

§Parameters

predicate - The predicate to determine whether to execute the function operation

§Returns

Returns a conditional function that only executes when the predicate returns true.

§Examples

use prism3_function::{BoxFunction, Function};

let double = BoxFunction::new(|x: i32| x * 2);
let conditional = double.when(|value: &i32| *value > 0);
assert_eq!(conditional.or_else(|_| 0).apply(5), 10);  // executed
assert_eq!(conditional.or_else(|_| 0).apply(-3), 0);  // not executed

Source

pub fn and_then<S, F>(self, after: F) -> BoxMutatingFunctionOnce<T, S>
where S: 'static, F: FunctionOnce<R, S> + 'static,

Chains execution with another function, executing the current function first, then the subsequent function.

§Parameters

after - The subsequent function to execute after the current function completes

§Returns

Returns a new function that executes the current function and the subsequent function in sequence.

§Examples

use prism3_function::{BoxFunction, Function};

let double = BoxFunction::new(|x: i32| x * 2);
let to_string = BoxFunction::new(|x: i32| x.to_string());

let chained = double.and_then(to_string);
assert_eq!(chained.apply(5), "10".to_string());

Source §

impl<T> BoxMutatingFunctionOnce<T, T>
where T: Clone + 'static,

Source

pub fn identity() -> BoxMutatingFunctionOnce<T, T>

Creates an identity function

§Examples

/// rust /// use prism3_function::BoxMutatingFunctionOnce; /// /// let mut identity = BoxMutatingFunctionOnce::<i32, i32>::identity(); /// let mut value = 42; /// assert_eq!(identity.apply(&mut value), 42); ///