Module mutating_function 

MutatingFunction Types

Provides Java-like MutatingFunction interface implementations for performing operations that accept a mutable reference and return a result.

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

This module provides a unified MutatingFunction trait and three concrete implementations based on different ownership models:

• BoxMutatingFunction<T, R>: Box-based single ownership implementation
• ArcMutatingFunction<T, R>: Arc-based thread-safe shared ownership implementation
• RcMutatingFunction<T, R>: Rc-based single-threaded shared ownership implementation

Design Philosophy

MutatingFunction bridges the gap between Function and Mutator:

• Function: Fn(&T) -> R - reads input, returns result
• Mutator: Fn(&mut T) - modifies input, no return
• MutatingFunction: Fn(&mut T) -> R - modifies input AND returns result

Comparison with Related Types

Type	Input	Modifies?	Returns?	Use Cases
Function	&T	❌	✅	Read-only transform
Mutator	&mut T	✅	❌	In-place modification
MutatingFunction	&mut T	✅	✅	Modify + return info
Transformer	T	N/A	✅	Consume + transform

Key Insight: Use MutatingFunction when you need to both modify the input and return information about the modification or the previous state.

Comparison Table

Feature	Box	Arc	Rc
Ownership	Single	Shared	Shared
Cloneable	❌	✅	✅
Thread-Safe	❌	✅	❌
Interior Mut.	N/A	N/A	N/A
and_then API	self	&self	&self
Lock Overhead	None	None	None

Use Cases

Common Scenarios

• Atomic operations: Increment counter and return new value
• Cache updates: Update cache and return old value
• Validation: Validate and fix data, return validation result
• Event handlers: Process event and return whether to continue
• State machines: Transition state and return transition info

Examples

Basic Usage

use prism3_function::{BoxMutatingFunction, MutatingFunction};

// Increment counter and return new value
let incrementer = BoxMutatingFunction::new(|x: &mut i32| {
    *x += 1;
    *x
});

let mut value = 5;
let result = incrementer.apply(&mut value);
assert_eq!(value, 6);
assert_eq!(result, 6);

Method Chaining

use prism3_function::{BoxMutatingFunction, MutatingFunction};

let chained = BoxMutatingFunction::new(|x: &mut i32| {
    *x *= 2;
    *x
})
.and_then(|x: &mut i32| {
    *x += 10;
    *x
});

let mut value = 5;
let result = chained.apply(&mut value);
assert_eq!(value, 20); // (5 * 2) + 10
assert_eq!(result, 20);

Cache Update Pattern

use prism3_function::{BoxMutatingFunction, MutatingFunction};
use std::collections::HashMap;

let updater = BoxMutatingFunction::new(
    |cache: &mut HashMap<String, i32>| {
        cache.insert("key".to_string(), 42)
    }
);

let mut cache = HashMap::new();
cache.insert("key".to_string(), 10);
let old_value = updater.apply(&mut cache);
assert_eq!(old_value, Some(10));
assert_eq!(cache.get("key"), Some(&42));

Author

Haixing Hu

Structs

ArcConditionalMutatingFunction

ArcConditionalMutatingFunction struct

ArcMutatingFunction

ArcMutatingFunction struct

BoxConditionalMutatingFunction

BoxConditionalMutatingFunction struct

BoxMutatingFunction

BoxMutatingFunction struct

RcConditionalMutatingFunction

RcConditionalMutatingFunction struct

RcMutatingFunction

RcMutatingFunction struct

Traits

FnMutatingFunctionOps

Extension trait for closures implementing the base function trait

MutatingFunction

MutatingFunction trait - Unified mutating function interface