Trait Mutator 

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

    // Provided methods
    fn into_box(self) -> BoxMutator<T>
       where Self: Sized + 'static,
             T: 'static { ... }
    fn into_rc(self) -> RcMutator<T>
       where Self: Sized + 'static,
             T: 'static { ... }
    fn into_arc(self) -> ArcMutator<T>
       where Self: Sized + Send + 'static,
             T: Send + 'static { ... }
    fn into_fn(self) -> impl FnMut(&mut T)
       where Self: Sized + 'static,
             T: 'static { ... }
    fn to_box(&self) -> BoxMutator<T>
       where Self: Sized + Clone + 'static,
             T: 'static { ... }
    fn to_rc(&self) -> RcMutator<T>
       where Self: Sized + Clone + 'static,
             T: 'static { ... }
    fn to_arc(&self) -> ArcMutator<T>
       where Self: Sized + Clone + Send + 'static,
             T: Send + 'static { ... }
    fn to_fn(&self) -> impl FnMut(&mut T)
       where Self: Sized + Clone + 'static,
             T: 'static { ... }
}

Mutator trait - Unified mutator interface

Defines the core behavior of all mutator types. Performs operations that accept a mutable reference and modify the input value (not just side effects).

This trait is automatically implemented by:

• All closures implementing FnMut(&mut T)
• BoxMutator<T>, ArcMutator<T>, and RcMutator<T>

Design Rationale

The trait provides a unified abstraction over different ownership models, allowing generic code to work with any mutator type. Type conversion methods (into_box, into_arc, into_rc) enable flexible ownership transitions based on usage requirements.

Features

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

Examples

Generic Mutator Function

use prism3_function::{Mutator, BoxMutator, ArcMutator};

fn apply_mutator<M: Mutator<i32>>(
    mutator: &mut M,
    value: i32
) -> i32 {
    let mut val = value;
    mutator.mutate(&mut val);
    val
}

// Works with any mutator type
let mut box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
assert_eq!(apply_mutator(&mut box_mut, 5), 10);

let mut arc_mut = ArcMutator::new(|x: &mut i32| *x *= 2);
assert_eq!(apply_mutator(&mut arc_mut, 5), 10);

let mut closure = |x: &mut i32| *x *= 2;
assert_eq!(apply_mutator(&mut closure, 5), 10);

Type Conversion

use prism3_function::Mutator;

let closure = |x: &mut i32| *x *= 2;

// Convert to different ownership models
let box_mutator = closure.into_box();
// let rc_mutator = closure.into_rc();  // closure moved
// let arc_mutator = closure.into_arc(); // closure moved

Author

Haixing Hu

Required Methods

fn mutate(&mut self, value: &mut T)

Performs the mutation operation

Executes an operation on the given mutable reference. The operation typically modifies the input value or produces side effects.

Parameters

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

Examples

use prism3_function::{Mutator, BoxMutator};

let mut mutator = BoxMutator::new(|x: &mut i32| *x *= 2);
let mut value = 5;
mutator.mutate(&mut value);
assert_eq!(value, 10);

Provided Methods

fn into_box(self) -> BoxMutator<T>

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

Convert this mutator into a BoxMutator<T>.

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

Consumption

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

Returns

A BoxMutator<T> that forwards to the original mutator.

Examples

use prism3_function::Mutator;

let closure = |x: &mut i32| *x *= 2;
let mut boxed = closure.into_box();
let mut value = 5;
boxed.mutate(&mut value);
assert_eq!(value, 10);

Examples found in repository

examples/mutator_demo.rs (line 319)

fn main() {
    println!("=== Mutator Demo ===\n");

    // ========================================================================
    // Example 1: BoxMutator Basic Usage
    // ========================================================================
    println!("Example 1: BoxMutator Basic Usage");
    println!("{}", "-".repeat(50));

    let mut mutator = BoxMutator::new(|x: &mut i32| {
        *x *= 2;
    });
    let mut value = 5;
    println!("Initial value: {}", value);
    mutator.mutate(&mut value);
    println!("After BoxMutator execution: {}\n", value);

    // ========================================================================
    // Example 2: BoxMutator Method Chaining
    // ========================================================================
    println!("Example 2: BoxMutator Method Chaining");
    println!("{}", "-".repeat(50));

    let mut chained = BoxMutator::new(|x: &mut i32| {
        *x *= 2; // multiply by 2
    })
    .and_then(|x: &mut i32| {
        *x += 10; // add 10
    })
    .and_then(|x: &mut i32| {
        *x = *x * *x; // square
    });

    let mut value = 5;
    println!("Initial value: {}", value);
    chained.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20, 20 * 20 = 400)\n", value);

    // ========================================================================
    // Example 3: Closure Extension Methods
    // ========================================================================
    println!("Example 3: Direct Use of Closure Extension Methods");
    println!("{}", "-".repeat(50));

    let mut closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20)\n", value);

    // ========================================================================
    // Example 4: BoxMutator Factory Methods
    // ========================================================================
    println!("Example 4: BoxMutator Factory Methods");
    println!("{}", "-".repeat(50));

    // noop
    let mut noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.mutate(&mut value);
    println!("After noop: {} (unchanged)\n", value);

    // ========================================================================
    // Example 5: Conditional Mutator
    // ========================================================================
    println!("Example 5: Conditional Mutator");
    println!("{}", "-".repeat(50));

    // when (conditional execution)
    let mut increment_if_positive = BoxMutator::new(|x: &mut i32| *x += 1).when(|x: &i32| *x > 0);

    let mut positive = 5;
    let mut negative = -5;
    println!(
        "Before when - positive: {}, negative: {}",
        positive, negative
    );
    increment_if_positive.mutate(&mut positive);
    increment_if_positive.mutate(&mut negative);
    println!(
        "After when - positive: {}, negative: {}\n",
        positive, negative
    );

    // when().or_else() (conditional branching)
    let mut adjust = BoxMutator::new(|x: &mut i32| *x *= 2)
        .when(|x: &i32| *x > 0)
        .or_else(|x: &mut i32| *x = -*x);

    let mut positive = 10;
    let mut negative = -10;
    println!(
        "Before when().or_else() - positive: {}, negative: {}",
        positive, negative
    );
    adjust.mutate(&mut positive);
    adjust.mutate(&mut negative);
    println!(
        "After when().or_else() - positive: {}, negative: {}\n",
        positive, negative
    );

    // ========================================================================
    // Example 6: ArcMutator - Multi-threaded Sharing
    // ========================================================================
    println!("Example 6: ArcMutator - Multi-threaded Sharing");
    println!("{}", "-".repeat(50));

    let shared = ArcMutator::new(|x: &mut i32| *x *= 2);

    // Clone for another thread
    let shared_clone = shared.clone();
    let handle = thread::spawn(move || {
        let mut value = 5;
        let mut mutator = shared_clone;
        mutator.mutate(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

    // Use in main thread
    let mut value = 3;
    let mut mutator = shared;
    mutator.mutate(&mut value);
    println!("Main thread: 3 * 2 = {}", value);

    let thread_result = handle.join().unwrap();
    println!("Thread result: {}\n", thread_result);

    // ========================================================================
    // Example 7: ArcMutator Composition (without consuming original mutator)
    // ========================================================================
    println!("Example 7: ArcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = ArcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = ArcMutator::new(|x: &mut i32| *x += 10);

    // Composition doesn't consume the original mutator
    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}", value2);

    // double and add_ten are still available
    let mut value3 = 10;
    let mut d = double;
    d.mutate(&mut value3);
    println!("Original double still available: 10 -> {}\n", value3);

    // ========================================================================
    // Example 8: RcMutator - Single-threaded Sharing
    // ========================================================================
    println!("Example 8: RcMutator - Single-threaded Sharing");
    println!("{}", "-".repeat(50));

    let rc_mutator = RcMutator::new(|x: &mut i32| *x *= 2);

    // Clone multiple copies
    let clone1 = rc_mutator.clone();
    let clone2 = rc_mutator.clone();

    let mut value1 = 5;
    let mut c1 = clone1;
    c1.mutate(&mut value1);
    println!("clone1: 5 -> {}", value1);

    let mut value2 = 3;
    let mut c2 = clone2;
    c2.mutate(&mut value2);
    println!("clone2: 3 -> {}", value2);

    let mut value3 = 7;
    let mut c3 = rc_mutator;
    c3.mutate(&mut value3);
    println!("Original: 7 -> {}\n", value3);

    // ========================================================================
    // Example 9: RcMutator Composition (borrowing &self)
    // ========================================================================
    println!("Example 9: RcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = RcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = RcMutator::new(|x: &mut i32| *x += 10);

    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}\n", value2);

    // ========================================================================
    // Example 10: Unified Mutator trait
    // ========================================================================
    println!("Example 10: Unified Mutator trait");
    println!("{}", "-".repeat(50));

    fn apply_to_all<M: Mutator<i32>>(mutator: &mut M, values: &mut [i32]) {
        for value in values.iter_mut() {
            mutator.mutate(value);
        }
    }

    let mut values1 = vec![1, 2, 3, 4, 5];
    let mut box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    println!("Using BoxMutator: {:?}", values1);
    apply_to_all(&mut box_mut, &mut values1);
    println!("Result: {:?}", values1);

    let mut values2 = vec![1, 2, 3, 4, 5];
    let mut arc_mut = ArcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using ArcMutator: {:?}", values2);
    apply_to_all(&mut arc_mut, &mut values2);
    println!("Result: {:?}", values2);

    let mut values3 = vec![1, 2, 3, 4, 5];
    let mut rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using RcMutator: {:?}", values3);
    apply_to_all(&mut rc_mut, &mut values3);
    println!("Result: {:?}", values3);

    let mut values4 = vec![1, 2, 3, 4, 5];
    let mut closure = |x: &mut i32| *x *= 2;
    println!("Using closure: {:?}", values4);
    apply_to_all(&mut closure, &mut values4);
    println!("Result: {:?}\n", values4);

    // ========================================================================
    // Example 11: Complex Data Processing Pipeline
    // ========================================================================
    println!("Example 11: Complex Data Processing Pipeline");
    println!("{}", "-".repeat(50));

    let mut pipeline = BoxMutator::new(|x: &mut i32| {
        // Validation: clamp to 0-100
        *x = (*x).clamp(0, 100);
    })
    .and_then(|x: &mut i32| {
        // Normalization: scale to 0-10
        *x /= 10;
    })
    .and_then(|x: &mut i32| {
        // Transformation: square
        *x = *x * *x;
    });

    let mut value1 = -50;
    pipeline.mutate(&mut value1);
    println!("-50 -> {}", value1);

    let mut value2 = 200;
    pipeline.mutate(&mut value2);
    println!("200 -> {}", value2);

    let mut value3 = 30;
    pipeline.mutate(&mut value3);
    println!("30 -> {}\n", value3);

    // ========================================================================
    // Example 12: String Processing
    // ========================================================================
    println!("Example 12: String Processing");
    println!("{}", "-".repeat(50));

    let mut string_processor = BoxMutator::new(|s: &mut String| s.retain(|c| !c.is_whitespace()))
        .and_then(|s: &mut String| *s = s.to_lowercase())
        .and_then(|s: &mut String| s.push_str("!!!"));

    let mut text = String::from("Hello World");
    println!("Original: {}", text);
    string_processor.mutate(&mut text);
    println!("After processing: {}\n", text);

    // ========================================================================
    // Example 13: Type Conversion
    // ========================================================================
    println!("Example 13: Type Conversion");
    println!("{}", "-".repeat(50));

    // Closure -> BoxMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut box_mut = closure.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

    // Closure -> RcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut rc_mut = closure.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("Closure -> RcMutator: 5 -> {}", value);

    // Closure -> ArcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut arc_mut = closure.into_arc();
    let mut value = 5;
    arc_mut.mutate(&mut value);
    println!("Closure -> ArcMutator: 5 -> {}", value);

    // BoxMutator -> RcMutator
    let box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    let mut rc_mut = box_mut.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("BoxMutator -> RcMutator: 5 -> {}", value);

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let mut box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("RcMutator -> BoxMutator: 5 -> {}\n", value);

    // ========================================================================
    // Example 14: Custom Types
    // ========================================================================
    println!("Example 14: Custom Types");
    println!("{}", "-".repeat(50));

    #[derive(Debug, Clone)]
    struct Point {
        x: i32,
        y: i32,
    }

    let mut processor = BoxMutator::new(|p: &mut Point| p.x *= 2)
        .and_then(|p: &mut Point| p.y *= 2)
        .and_then(|p: &mut Point| p.x += p.y);

    let mut point = Point { x: 3, y: 4 };
    println!("Original point: {:?}", point);
    processor.mutate(&mut point);
    println!("After processing: {:?}\n", point);

    println!("=== All Examples Completed ===");
}

fn into_rc(self) -> RcMutator<T>

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

Convert this mutator into an RcMutator<T>.

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

Consumption

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

Returns

An RcMutator<T> forwarding to the original mutator.

Examples

use prism3_function::Mutator;

let closure = |x: &mut i32| *x *= 2;
let mut rc = closure.into_rc();
let mut value = 5;
rc.mutate(&mut value);
assert_eq!(value, 10);

Examples found in repository

examples/mutator_demo.rs (line 326)

fn main() {
    println!("=== Mutator Demo ===\n");

    // ========================================================================
    // Example 1: BoxMutator Basic Usage
    // ========================================================================
    println!("Example 1: BoxMutator Basic Usage");
    println!("{}", "-".repeat(50));

    let mut mutator = BoxMutator::new(|x: &mut i32| {
        *x *= 2;
    });
    let mut value = 5;
    println!("Initial value: {}", value);
    mutator.mutate(&mut value);
    println!("After BoxMutator execution: {}\n", value);

    // ========================================================================
    // Example 2: BoxMutator Method Chaining
    // ========================================================================
    println!("Example 2: BoxMutator Method Chaining");
    println!("{}", "-".repeat(50));

    let mut chained = BoxMutator::new(|x: &mut i32| {
        *x *= 2; // multiply by 2
    })
    .and_then(|x: &mut i32| {
        *x += 10; // add 10
    })
    .and_then(|x: &mut i32| {
        *x = *x * *x; // square
    });

    let mut value = 5;
    println!("Initial value: {}", value);
    chained.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20, 20 * 20 = 400)\n", value);

    // ========================================================================
    // Example 3: Closure Extension Methods
    // ========================================================================
    println!("Example 3: Direct Use of Closure Extension Methods");
    println!("{}", "-".repeat(50));

    let mut closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20)\n", value);

    // ========================================================================
    // Example 4: BoxMutator Factory Methods
    // ========================================================================
    println!("Example 4: BoxMutator Factory Methods");
    println!("{}", "-".repeat(50));

    // noop
    let mut noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.mutate(&mut value);
    println!("After noop: {} (unchanged)\n", value);

    // ========================================================================
    // Example 5: Conditional Mutator
    // ========================================================================
    println!("Example 5: Conditional Mutator");
    println!("{}", "-".repeat(50));

    // when (conditional execution)
    let mut increment_if_positive = BoxMutator::new(|x: &mut i32| *x += 1).when(|x: &i32| *x > 0);

    let mut positive = 5;
    let mut negative = -5;
    println!(
        "Before when - positive: {}, negative: {}",
        positive, negative
    );
    increment_if_positive.mutate(&mut positive);
    increment_if_positive.mutate(&mut negative);
    println!(
        "After when - positive: {}, negative: {}\n",
        positive, negative
    );

    // when().or_else() (conditional branching)
    let mut adjust = BoxMutator::new(|x: &mut i32| *x *= 2)
        .when(|x: &i32| *x > 0)
        .or_else(|x: &mut i32| *x = -*x);

    let mut positive = 10;
    let mut negative = -10;
    println!(
        "Before when().or_else() - positive: {}, negative: {}",
        positive, negative
    );
    adjust.mutate(&mut positive);
    adjust.mutate(&mut negative);
    println!(
        "After when().or_else() - positive: {}, negative: {}\n",
        positive, negative
    );

    // ========================================================================
    // Example 6: ArcMutator - Multi-threaded Sharing
    // ========================================================================
    println!("Example 6: ArcMutator - Multi-threaded Sharing");
    println!("{}", "-".repeat(50));

    let shared = ArcMutator::new(|x: &mut i32| *x *= 2);

    // Clone for another thread
    let shared_clone = shared.clone();
    let handle = thread::spawn(move || {
        let mut value = 5;
        let mut mutator = shared_clone;
        mutator.mutate(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

    // Use in main thread
    let mut value = 3;
    let mut mutator = shared;
    mutator.mutate(&mut value);
    println!("Main thread: 3 * 2 = {}", value);

    let thread_result = handle.join().unwrap();
    println!("Thread result: {}\n", thread_result);

    // ========================================================================
    // Example 7: ArcMutator Composition (without consuming original mutator)
    // ========================================================================
    println!("Example 7: ArcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = ArcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = ArcMutator::new(|x: &mut i32| *x += 10);

    // Composition doesn't consume the original mutator
    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}", value2);

    // double and add_ten are still available
    let mut value3 = 10;
    let mut d = double;
    d.mutate(&mut value3);
    println!("Original double still available: 10 -> {}\n", value3);

    // ========================================================================
    // Example 8: RcMutator - Single-threaded Sharing
    // ========================================================================
    println!("Example 8: RcMutator - Single-threaded Sharing");
    println!("{}", "-".repeat(50));

    let rc_mutator = RcMutator::new(|x: &mut i32| *x *= 2);

    // Clone multiple copies
    let clone1 = rc_mutator.clone();
    let clone2 = rc_mutator.clone();

    let mut value1 = 5;
    let mut c1 = clone1;
    c1.mutate(&mut value1);
    println!("clone1: 5 -> {}", value1);

    let mut value2 = 3;
    let mut c2 = clone2;
    c2.mutate(&mut value2);
    println!("clone2: 3 -> {}", value2);

    let mut value3 = 7;
    let mut c3 = rc_mutator;
    c3.mutate(&mut value3);
    println!("Original: 7 -> {}\n", value3);

    // ========================================================================
    // Example 9: RcMutator Composition (borrowing &self)
    // ========================================================================
    println!("Example 9: RcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = RcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = RcMutator::new(|x: &mut i32| *x += 10);

    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}\n", value2);

    // ========================================================================
    // Example 10: Unified Mutator trait
    // ========================================================================
    println!("Example 10: Unified Mutator trait");
    println!("{}", "-".repeat(50));

    fn apply_to_all<M: Mutator<i32>>(mutator: &mut M, values: &mut [i32]) {
        for value in values.iter_mut() {
            mutator.mutate(value);
        }
    }

    let mut values1 = vec![1, 2, 3, 4, 5];
    let mut box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    println!("Using BoxMutator: {:?}", values1);
    apply_to_all(&mut box_mut, &mut values1);
    println!("Result: {:?}", values1);

    let mut values2 = vec![1, 2, 3, 4, 5];
    let mut arc_mut = ArcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using ArcMutator: {:?}", values2);
    apply_to_all(&mut arc_mut, &mut values2);
    println!("Result: {:?}", values2);

    let mut values3 = vec![1, 2, 3, 4, 5];
    let mut rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using RcMutator: {:?}", values3);
    apply_to_all(&mut rc_mut, &mut values3);
    println!("Result: {:?}", values3);

    let mut values4 = vec![1, 2, 3, 4, 5];
    let mut closure = |x: &mut i32| *x *= 2;
    println!("Using closure: {:?}", values4);
    apply_to_all(&mut closure, &mut values4);
    println!("Result: {:?}\n", values4);

    // ========================================================================
    // Example 11: Complex Data Processing Pipeline
    // ========================================================================
    println!("Example 11: Complex Data Processing Pipeline");
    println!("{}", "-".repeat(50));

    let mut pipeline = BoxMutator::new(|x: &mut i32| {
        // Validation: clamp to 0-100
        *x = (*x).clamp(0, 100);
    })
    .and_then(|x: &mut i32| {
        // Normalization: scale to 0-10
        *x /= 10;
    })
    .and_then(|x: &mut i32| {
        // Transformation: square
        *x = *x * *x;
    });

    let mut value1 = -50;
    pipeline.mutate(&mut value1);
    println!("-50 -> {}", value1);

    let mut value2 = 200;
    pipeline.mutate(&mut value2);
    println!("200 -> {}", value2);

    let mut value3 = 30;
    pipeline.mutate(&mut value3);
    println!("30 -> {}\n", value3);

    // ========================================================================
    // Example 12: String Processing
    // ========================================================================
    println!("Example 12: String Processing");
    println!("{}", "-".repeat(50));

    let mut string_processor = BoxMutator::new(|s: &mut String| s.retain(|c| !c.is_whitespace()))
        .and_then(|s: &mut String| *s = s.to_lowercase())
        .and_then(|s: &mut String| s.push_str("!!!"));

    let mut text = String::from("Hello World");
    println!("Original: {}", text);
    string_processor.mutate(&mut text);
    println!("After processing: {}\n", text);

    // ========================================================================
    // Example 13: Type Conversion
    // ========================================================================
    println!("Example 13: Type Conversion");
    println!("{}", "-".repeat(50));

    // Closure -> BoxMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut box_mut = closure.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

    // Closure -> RcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut rc_mut = closure.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("Closure -> RcMutator: 5 -> {}", value);

    // Closure -> ArcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut arc_mut = closure.into_arc();
    let mut value = 5;
    arc_mut.mutate(&mut value);
    println!("Closure -> ArcMutator: 5 -> {}", value);

    // BoxMutator -> RcMutator
    let box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    let mut rc_mut = box_mut.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("BoxMutator -> RcMutator: 5 -> {}", value);

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let mut box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("RcMutator -> BoxMutator: 5 -> {}\n", value);

    // ========================================================================
    // Example 14: Custom Types
    // ========================================================================
    println!("Example 14: Custom Types");
    println!("{}", "-".repeat(50));

    #[derive(Debug, Clone)]
    struct Point {
        x: i32,
        y: i32,
    }

    let mut processor = BoxMutator::new(|p: &mut Point| p.x *= 2)
        .and_then(|p: &mut Point| p.y *= 2)
        .and_then(|p: &mut Point| p.x += p.y);

    let mut point = Point { x: 3, y: 4 };
    println!("Original point: {:?}", point);
    processor.mutate(&mut point);
    println!("After processing: {:?}\n", point);

    println!("=== All Examples Completed ===");
}

fn into_arc(self) -> ArcMutator<T>

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

Convert this mutator into an ArcMutator<T>.

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

Consumption

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

Returns

An ArcMutator<T> that forwards to the original mutator.

Examples

use prism3_function::Mutator;

let closure = |x: &mut i32| *x *= 2;
let mut arc = closure.into_arc();
let mut value = 5;
arc.mutate(&mut value);
assert_eq!(value, 10);

Examples found in repository

examples/mutator_demo.rs (line 333)

fn main() {
    println!("=== Mutator Demo ===\n");

    // ========================================================================
    // Example 1: BoxMutator Basic Usage
    // ========================================================================
    println!("Example 1: BoxMutator Basic Usage");
    println!("{}", "-".repeat(50));

    let mut mutator = BoxMutator::new(|x: &mut i32| {
        *x *= 2;
    });
    let mut value = 5;
    println!("Initial value: {}", value);
    mutator.mutate(&mut value);
    println!("After BoxMutator execution: {}\n", value);

    // ========================================================================
    // Example 2: BoxMutator Method Chaining
    // ========================================================================
    println!("Example 2: BoxMutator Method Chaining");
    println!("{}", "-".repeat(50));

    let mut chained = BoxMutator::new(|x: &mut i32| {
        *x *= 2; // multiply by 2
    })
    .and_then(|x: &mut i32| {
        *x += 10; // add 10
    })
    .and_then(|x: &mut i32| {
        *x = *x * *x; // square
    });

    let mut value = 5;
    println!("Initial value: {}", value);
    chained.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20, 20 * 20 = 400)\n", value);

    // ========================================================================
    // Example 3: Closure Extension Methods
    // ========================================================================
    println!("Example 3: Direct Use of Closure Extension Methods");
    println!("{}", "-".repeat(50));

    let mut closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.mutate(&mut value);
    println!("Result: {} (5 * 2 + 10 = 20)\n", value);

    // ========================================================================
    // Example 4: BoxMutator Factory Methods
    // ========================================================================
    println!("Example 4: BoxMutator Factory Methods");
    println!("{}", "-".repeat(50));

    // noop
    let mut noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.mutate(&mut value);
    println!("After noop: {} (unchanged)\n", value);

    // ========================================================================
    // Example 5: Conditional Mutator
    // ========================================================================
    println!("Example 5: Conditional Mutator");
    println!("{}", "-".repeat(50));

    // when (conditional execution)
    let mut increment_if_positive = BoxMutator::new(|x: &mut i32| *x += 1).when(|x: &i32| *x > 0);

    let mut positive = 5;
    let mut negative = -5;
    println!(
        "Before when - positive: {}, negative: {}",
        positive, negative
    );
    increment_if_positive.mutate(&mut positive);
    increment_if_positive.mutate(&mut negative);
    println!(
        "After when - positive: {}, negative: {}\n",
        positive, negative
    );

    // when().or_else() (conditional branching)
    let mut adjust = BoxMutator::new(|x: &mut i32| *x *= 2)
        .when(|x: &i32| *x > 0)
        .or_else(|x: &mut i32| *x = -*x);

    let mut positive = 10;
    let mut negative = -10;
    println!(
        "Before when().or_else() - positive: {}, negative: {}",
        positive, negative
    );
    adjust.mutate(&mut positive);
    adjust.mutate(&mut negative);
    println!(
        "After when().or_else() - positive: {}, negative: {}\n",
        positive, negative
    );

    // ========================================================================
    // Example 6: ArcMutator - Multi-threaded Sharing
    // ========================================================================
    println!("Example 6: ArcMutator - Multi-threaded Sharing");
    println!("{}", "-".repeat(50));

    let shared = ArcMutator::new(|x: &mut i32| *x *= 2);

    // Clone for another thread
    let shared_clone = shared.clone();
    let handle = thread::spawn(move || {
        let mut value = 5;
        let mut mutator = shared_clone;
        mutator.mutate(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

    // Use in main thread
    let mut value = 3;
    let mut mutator = shared;
    mutator.mutate(&mut value);
    println!("Main thread: 3 * 2 = {}", value);

    let thread_result = handle.join().unwrap();
    println!("Thread result: {}\n", thread_result);

    // ========================================================================
    // Example 7: ArcMutator Composition (without consuming original mutator)
    // ========================================================================
    println!("Example 7: ArcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = ArcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = ArcMutator::new(|x: &mut i32| *x += 10);

    // Composition doesn't consume the original mutator
    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}", value2);

    // double and add_ten are still available
    let mut value3 = 10;
    let mut d = double;
    d.mutate(&mut value3);
    println!("Original double still available: 10 -> {}\n", value3);

    // ========================================================================
    // Example 8: RcMutator - Single-threaded Sharing
    // ========================================================================
    println!("Example 8: RcMutator - Single-threaded Sharing");
    println!("{}", "-".repeat(50));

    let rc_mutator = RcMutator::new(|x: &mut i32| *x *= 2);

    // Clone multiple copies
    let clone1 = rc_mutator.clone();
    let clone2 = rc_mutator.clone();

    let mut value1 = 5;
    let mut c1 = clone1;
    c1.mutate(&mut value1);
    println!("clone1: 5 -> {}", value1);

    let mut value2 = 3;
    let mut c2 = clone2;
    c2.mutate(&mut value2);
    println!("clone2: 3 -> {}", value2);

    let mut value3 = 7;
    let mut c3 = rc_mutator;
    c3.mutate(&mut value3);
    println!("Original: 7 -> {}\n", value3);

    // ========================================================================
    // Example 9: RcMutator Composition (borrowing &self)
    // ========================================================================
    println!("Example 9: RcMutator Composition (borrowing &self)");
    println!("{}", "-".repeat(50));

    let double = RcMutator::new(|x: &mut i32| *x *= 2);
    let add_ten = RcMutator::new(|x: &mut i32| *x += 10);

    let pipeline1 = double.and_then(&add_ten);
    let pipeline2 = add_ten.and_then(&double);

    let mut value1 = 5;
    let mut p1 = pipeline1;
    p1.mutate(&mut value1);
    println!("pipeline1 (double then add): 5 -> {}", value1);

    let mut value2 = 5;
    let mut p2 = pipeline2;
    p2.mutate(&mut value2);
    println!("pipeline2 (add then double): 5 -> {}\n", value2);

    // ========================================================================
    // Example 10: Unified Mutator trait
    // ========================================================================
    println!("Example 10: Unified Mutator trait");
    println!("{}", "-".repeat(50));

    fn apply_to_all<M: Mutator<i32>>(mutator: &mut M, values: &mut [i32]) {
        for value in values.iter_mut() {
            mutator.mutate(value);
        }
    }

    let mut values1 = vec![1, 2, 3, 4, 5];
    let mut box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    println!("Using BoxMutator: {:?}", values1);
    apply_to_all(&mut box_mut, &mut values1);
    println!("Result: {:?}", values1);

    let mut values2 = vec![1, 2, 3, 4, 5];
    let mut arc_mut = ArcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using ArcMutator: {:?}", values2);
    apply_to_all(&mut arc_mut, &mut values2);
    println!("Result: {:?}", values2);

    let mut values3 = vec![1, 2, 3, 4, 5];
    let mut rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    println!("Using RcMutator: {:?}", values3);
    apply_to_all(&mut rc_mut, &mut values3);
    println!("Result: {:?}", values3);

    let mut values4 = vec![1, 2, 3, 4, 5];
    let mut closure = |x: &mut i32| *x *= 2;
    println!("Using closure: {:?}", values4);
    apply_to_all(&mut closure, &mut values4);
    println!("Result: {:?}\n", values4);

    // ========================================================================
    // Example 11: Complex Data Processing Pipeline
    // ========================================================================
    println!("Example 11: Complex Data Processing Pipeline");
    println!("{}", "-".repeat(50));

    let mut pipeline = BoxMutator::new(|x: &mut i32| {
        // Validation: clamp to 0-100
        *x = (*x).clamp(0, 100);
    })
    .and_then(|x: &mut i32| {
        // Normalization: scale to 0-10
        *x /= 10;
    })
    .and_then(|x: &mut i32| {
        // Transformation: square
        *x = *x * *x;
    });

    let mut value1 = -50;
    pipeline.mutate(&mut value1);
    println!("-50 -> {}", value1);

    let mut value2 = 200;
    pipeline.mutate(&mut value2);
    println!("200 -> {}", value2);

    let mut value3 = 30;
    pipeline.mutate(&mut value3);
    println!("30 -> {}\n", value3);

    // ========================================================================
    // Example 12: String Processing
    // ========================================================================
    println!("Example 12: String Processing");
    println!("{}", "-".repeat(50));

    let mut string_processor = BoxMutator::new(|s: &mut String| s.retain(|c| !c.is_whitespace()))
        .and_then(|s: &mut String| *s = s.to_lowercase())
        .and_then(|s: &mut String| s.push_str("!!!"));

    let mut text = String::from("Hello World");
    println!("Original: {}", text);
    string_processor.mutate(&mut text);
    println!("After processing: {}\n", text);

    // ========================================================================
    // Example 13: Type Conversion
    // ========================================================================
    println!("Example 13: Type Conversion");
    println!("{}", "-".repeat(50));

    // Closure -> BoxMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut box_mut = closure.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

    // Closure -> RcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut rc_mut = closure.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("Closure -> RcMutator: 5 -> {}", value);

    // Closure -> ArcMutator
    let closure = |x: &mut i32| *x *= 2;
    let mut arc_mut = closure.into_arc();
    let mut value = 5;
    arc_mut.mutate(&mut value);
    println!("Closure -> ArcMutator: 5 -> {}", value);

    // BoxMutator -> RcMutator
    let box_mut = BoxMutator::new(|x: &mut i32| *x *= 2);
    let mut rc_mut = box_mut.into_rc();
    let mut value = 5;
    rc_mut.mutate(&mut value);
    println!("BoxMutator -> RcMutator: 5 -> {}", value);

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let mut box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.mutate(&mut value);
    println!("RcMutator -> BoxMutator: 5 -> {}\n", value);

    // ========================================================================
    // Example 14: Custom Types
    // ========================================================================
    println!("Example 14: Custom Types");
    println!("{}", "-".repeat(50));

    #[derive(Debug, Clone)]
    struct Point {
        x: i32,
        y: i32,
    }

    let mut processor = BoxMutator::new(|p: &mut Point| p.x *= 2)
        .and_then(|p: &mut Point| p.y *= 2)
        .and_then(|p: &mut Point| p.x += p.y);

    let mut point = Point { x: 3, y: 4 };
    println!("Original point: {:?}", point);
    processor.mutate(&mut point);
    println!("After processing: {:?}\n", point);

    println!("=== All Examples Completed ===");
}

fn into_fn(self) -> impl FnMut(&mut T)

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

Consume the mutator and return an FnMut(&mut T) closure.

The returned closure forwards calls to the original mutator and is suitable for use with iterator adapters such as for_each.

Consumption

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

Returns

A closure implementing FnMut(&mut T) which forwards to the original mutator.

Examples

use prism3_function::{Mutator, BoxMutator};

let mutator = BoxMutator::new(|x: &mut i32| *x *= 2);
let mut values = vec![1, 2, 3, 4, 5];
values.iter_mut().for_each(mutator.into_fn());
assert_eq!(values, vec![2, 4, 6, 8, 10]);

fn to_box(&self) -> BoxMutator<T>

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

Create a non-consuming BoxMutator<T> that forwards to self.

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

Returns

A BoxMutator<T> that forwards to a clone of self.

fn to_rc(&self) -> RcMutator<T>

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

Create a non-consuming RcMutator<T> that forwards to self.

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

Returns

An RcMutator<T> that forwards to a clone of self.

fn to_arc(&self) -> ArcMutator<T>

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

Create a non-consuming ArcMutator<T> that forwards to self.

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

Returns

An ArcMutator<T> that forwards to a clone of self.

fn to_fn(&self) -> impl FnMut(&mut T)

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

Create a boxed FnMut(&mut T) 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) which forwards to the original mutator.

Implementors

impl<T> Mutator<T> for ArcConditionalMutator<T>

where T: Send + 'static,

impl<T> Mutator<T> for ArcMutator<T>

impl<T> Mutator<T> for BoxConditionalMutator<T>

where T: 'static,

impl<T> Mutator<T> for BoxMutator<T>

impl<T> Mutator<T> for RcConditionalMutator<T>

where T: 'static,

impl<T> Mutator<T> for RcMutator<T>

impl<T, F> Mutator<T> for F

where F: FnMut(&mut T),