StatefulMutatingFunction

prism3_function::functions::stateful_mutating_function

Trait StatefulMutatingFunction 

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

    // Provided methods
    fn into_box(self) -> BoxStatefulMutatingFunction<T, R>
       where Self: Sized + 'static,
             T: 'static,
             R: 'static { ... }
    fn into_rc(self) -> RcStatefulMutatingFunction<T, R>
       where Self: Sized + 'static,
             T: 'static,
             R: 'static { ... }
    fn into_arc(self) -> ArcStatefulMutatingFunction<T, R>
       where Self: Sized + Send + 'static,
             T: Send + 'static,
             R: Send + 'static { ... }
    fn into_fn(self) -> impl FnMut(&mut T) -> R
       where Self: Sized + 'static,
             T: 'static,
             R: 'static { ... }
    fn to_box(&self) -> BoxStatefulMutatingFunction<T, R>
       where Self: Sized + Clone + 'static,
             T: 'static,
             R: 'static { ... }
    fn to_rc(&self) -> RcStatefulMutatingFunction<T, R>
       where Self: Sized + Clone + 'static,
             T: 'static,
             R: 'static { ... }
    fn to_arc(&self) -> ArcStatefulMutatingFunction<T, R>
       where Self: Sized + Clone + Send + 'static,
             T: Send + 'static,
             R: Send + 'static { ... }
    fn to_fn(&self) -> impl FnMut(&mut T) -> R
       where Self: Sized + Clone + 'static,
             T: 'static,
             R: 'static { ... }
    fn into_once(self) -> BoxMutatingFunctionOnce<T, R>
       where Self: Sized + 'static,
             T: 'static,
             R: 'static { ... }
    fn to_once(&self) -> BoxMutatingFunctionOnce<T, R>
       where Self: Clone + 'static,
             T: 'static,
             R: 'static { ... }
}
Expand description

StatefulMutatingFunction trait - Unified stateful mutating function interface

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

Defines the core behavior of all stateful mutating function types. Performs operations that accept a mutable reference, potentially modify both the function’s internal state and the input, and return a result.

This trait is automatically implemented by:

  • All closures implementing FnMut(&mut T) -> R
  • BoxStatefulMutatingFunction<T, R>, ArcStatefulMutatingFunction<T, R>, and RcStatefulMutatingFunction<T, R>

§Design Rationale

The trait provides a unified abstraction over different ownership models for operations that need to maintain state while modifying input and returning results. This is useful for scenarios where you need to:

  • Track statistics or counts during modifications
  • Accumulate information across multiple calls
  • Implement stateful validators or transformers

§Features

  • Unified Interface: All stateful mutating function types share the same apply method signature
  • Automatic Implementation: Closures automatically implement this trait
  • Type Conversions: Easy conversion between ownership models
  • Generic Programming: Write functions that work with any stateful mutating function type

§Examples

§Generic Function

use prism3_function::{StatefulMutatingFunction,
                      BoxStatefulMutatingFunction};

fn apply_and_log<F: StatefulMutatingFunction<i32, i32>>(
    func: &mut F,
    value: i32
) -> i32 {
    let mut val = value;
    let result = func.apply(&mut val);
    println!("Modified: {} -> {}, returned: {}", value, val, result);
    result
}

let mut counter = {
    let mut count = 0;
    BoxStatefulMutatingFunction::new(move |x: &mut i32| {
        count += 1;
        *x += 1;
        count
    })
};
assert_eq!(apply_and_log(&mut counter, 5), 1);

§Type Conversion

use prism3_function::StatefulMutatingFunction;

let mut count = 0;
let closure = move |x: &mut i32| {
    count += 1;
    *x *= 2;
    count
};

// Convert to different ownership models
let mut box_func = closure.into_box();
// let mut rc_func = closure.into_rc();  // closure moved
// let mut arc_func = closure.into_arc(); // closure moved

§Author

Haixing Hu

Required Methods§

Source

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

Applies the function to the mutable reference and returns a result

Executes an operation on the given mutable reference, potentially modifying both the function’s internal state and the input, and returns a result value.

§Parameters
  • t - A mutable reference to the input value
§Returns

The computed result value

§Examples
use prism3_function::{StatefulMutatingFunction,
                      BoxStatefulMutatingFunction};

let mut counter = {
    let mut count = 0;
    BoxStatefulMutatingFunction::new(move |x: &mut i32| {
        count += 1;
        let old = *x;
        *x += 1;
        (old, count)
    })
};

let mut value = 5;
let (old_value, call_count) = counter.apply(&mut value);
assert_eq!(old_value, 5);
assert_eq!(call_count, 1);
assert_eq!(value, 6);

Provided Methods§

Source

fn into_box(self) -> BoxStatefulMutatingFunction<T, R>
where Self: Sized + 'static, T: 'static, R: 'static,

Convert this function into a BoxStatefulMutatingFunction<T, R>.

This consuming conversion takes ownership of self and returns a boxed implementation that forwards calls to the original function. Types that can provide a more efficient conversion may override the default implementation.

§Consumption

This method consumes the function: the original value will no longer be available after the call. For cloneable functions call .clone() before converting if you need to retain the original instance.

§Returns

A BoxStatefulMutatingFunction<T, R> that forwards to the original function.

§Examples
use prism3_function::StatefulMutatingFunction;

let mut count = 0;
let closure = move |x: &mut i32| {
    count += 1;
    *x *= 2;
    count
};
let mut boxed = closure.into_box();
let mut value = 5;
assert_eq!(boxed.apply(&mut value), 1);
Source

fn into_rc(self) -> RcStatefulMutatingFunction<T, R>
where Self: Sized + 'static, T: 'static, R: 'static,

Convert this function into an RcStatefulMutatingFunction<T, R>.

This consuming conversion takes ownership of self and returns an Rc-backed function that forwards calls to the original. Override to provide a more direct or efficient conversion when available.

§Consumption

This method consumes the function. If you need to keep the original instance, clone it prior to calling this method.

§Returns

An RcStatefulMutatingFunction<T, R> forwarding to the original function.

§Examples
use prism3_function::StatefulMutatingFunction;

let mut count = 0;
let closure = move |x: &mut i32| {
    count += 1;
    *x *= 2;
    count
};
let mut rc = closure.into_rc();
let mut value = 5;
assert_eq!(rc.apply(&mut value), 1);
Source

fn into_arc(self) -> ArcStatefulMutatingFunction<T, R>
where Self: Sized + Send + 'static, T: Send + 'static, R: Send + 'static,

Convert this function into an ArcStatefulMutatingFunction<T, R>.

This consuming conversion takes ownership of self and returns an Arc-wrapped, thread-safe function. Types may override the default implementation to provide a more efficient conversion.

§Consumption

This method consumes the function. Clone the instance first if you need to retain the original for further use.

§Returns

An ArcStatefulMutatingFunction<T, R> that forwards to the original function.

§Examples
use prism3_function::StatefulMutatingFunction;

let mut count = 0;
let closure = move |x: &mut i32| {
    count += 1;
    *x *= 2;
    count
};
let mut arc = closure.into_arc();
let mut value = 5;
assert_eq!(arc.apply(&mut value), 1);
Source

fn into_fn(self) -> impl FnMut(&mut T) -> R
where Self: Sized + 'static, T: 'static, R: 'static,

Consume the function and return an FnMut(&mut T) -> R closure.

The returned closure forwards calls to the original function and is suitable for use with iterator adapters or other contexts expecting closures.

§Consumption

This method consumes the function. The original instance will not be available after calling this method.

§Returns

A closure implementing FnMut(&mut T) -> R which forwards to the original function.

§Examples
use prism3_function::{StatefulMutatingFunction,
                      BoxStatefulMutatingFunction};

let func = {
    let mut sum = 0;
    BoxStatefulMutatingFunction::new(move |x: &mut i32| {
        *x *= 2;
        sum += *x;
        sum
    })
};
let mut closure = func.into_fn();
let mut value = 5;
assert_eq!(closure(&mut value), 10);
Source

fn to_box(&self) -> BoxStatefulMutatingFunction<T, R>
where Self: Sized + Clone + 'static, T: 'static, R: 'static,

Create a non-consuming BoxStatefulMutatingFunction<T, R> that forwards to self.

The default implementation clones self (requires Clone) and returns a boxed function that calls the cloned instance. Override this method if a more efficient conversion exists.

§Returns

A BoxStatefulMutatingFunction<T, R> that forwards to a clone of self.

Source

fn to_rc(&self) -> RcStatefulMutatingFunction<T, R>
where Self: Sized + Clone + 'static, T: 'static, R: 'static,

Create a non-consuming RcStatefulMutatingFunction<T, R> that forwards to self.

The default implementation clones self (requires Clone) and returns an Rc-backed function that forwards calls to the clone. Override to provide a more direct or efficient conversion if needed.

§Returns

An RcStatefulMutatingFunction<T, R> that forwards to a clone of self.

Source

fn to_arc(&self) -> ArcStatefulMutatingFunction<T, R>
where Self: Sized + Clone + Send + 'static, T: Send + 'static, R: Send + 'static,

Create a non-consuming ArcStatefulMutatingFunction<T, R> that forwards to self.

The default implementation clones self (requires Clone + Send) and returns an Arc-wrapped function that forwards calls to the clone. Override when a more efficient conversion is available.

§Returns

An ArcStatefulMutatingFunction<T, R> that forwards to a clone of self.

Source

fn to_fn(&self) -> impl FnMut(&mut T) -> R
where Self: Sized + Clone + 'static, T: 'static, R: 'static,

Create a boxed FnMut(&mut T) -> R closure that forwards to self.

The default implementation clones self (requires Clone) and returns a boxed closure that invokes the cloned instance. Override to provide a more efficient conversion when possible.

§Returns

A closure implementing FnMut(&mut T) -> R which forwards to the original function.

Source

fn into_once(self) -> BoxMutatingFunctionOnce<T, R>
where Self: Sized + 'static, T: 'static, R: 'static,

Convert to StatefulMutatingFunctionOnce

⚠️ Consumes self: The original function will be unavailable after calling this method.

Converts a reusable stateful mutating function to a one-time function that consumes itself on use. This enables passing StatefulMutatingFunction to functions that require StatefulMutatingFunctionOnce.

§Returns

Returns a BoxMutatingFunctionOnce<T, R>

§Examples
use prism3_function::{StatefulMutatingFunctionOnce,
                      StatefulMutatingFunction,
                      BoxStatefulMutatingFunction};

fn takes_once<F: StatefulMutatingFunctionOnce<i32, i32>>(func: F, value: &mut i32) {
    let result = func.apply(value);
    println!("Result: {}", result);
}

let func = BoxStatefulMutatingFunction::new(|x: &mut i32| {
    *x *= 2;
    *x
});
let mut value = 5;
takes_once(func.into_once(), &mut value);
Source

fn to_once(&self) -> BoxMutatingFunctionOnce<T, R>
where Self: Clone + 'static, T: 'static, R: 'static,

Convert to StatefulMutatingFunctionOnce without consuming self

⚠️ Requires Clone: This method requires Self to implement Clone. Clones the current function and converts the clone to a one-time function.

§Returns

Returns a BoxMutatingFunctionOnce<T, R>

§Examples
use prism3_function::{StatefulMutatingFunctionOnce,
                      StatefulMutatingFunction,
                      BoxStatefulMutatingFunction};

fn takes_once<F: StatefulMutatingFunctionOnce<i32, i32>>(func: F, value: &mut i32) {
    let result = func.apply(value);
    println!("Result: {}", result);
}

let func = BoxStatefulMutatingFunction::new(|x: &mut i32| {
    *x *= 2;
    *x
});
let mut value = 5;
takes_once(func.to_once(), &mut value);

Implementors§