Trait Mutator 

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

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

Mutator trait - Unified stateless mutator interface

Defines the core behavior of all stateless mutator types. Performs operations that accept a mutable reference and modify the input value without maintaining internal state.

This trait is automatically implemented by:

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

Design Rationale

The trait provides a unified abstraction over different ownership models for stateless operations. Unlike StatefulMutator which uses FnMut and can modify its internal state, Mutator uses Fn for pure transformations.

Features

• Stateless Operations: No internal state modification (&self not &mut self)
• Unified Interface: All mutator types share the same mutate method signature
• Automatic Implementation: Closures automatically implement this trait
• Type Conversions: Easy conversion between ownership models
• Generic Programming: Write functions that work with any mutator type

Examples

Generic Mutator Function

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

fn apply_mutator<M: Mutator<i32>>(
    mutator: &mut M,
    value: i32
) -> i32 {
    let mut val = value;
    mutator.apply(&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 qubit_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

Required Methods

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

Performs the stateless mutation operation

Executes an operation on the given mutable reference without modifying the mutator’s internal state. This is a pure transformation operation.

Parameters

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

Examples

use qubit_function::{Mutator, BoxMutator};

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

Provided Methods

fn into_box(self) -> BoxMutator<T>

where Self: Sized + '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 qubit_function::Mutator;

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

Examples found in repository

examples/mutators/mutator_demo.rs (line 320)

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

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

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

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

    let 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.apply(&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 closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.apply(&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 noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.apply(&mut value);
    println!("After noop: {} (unchanged)\n", value);

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

    // when (conditional execution)
    let 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.apply(&mut positive);
    increment_if_positive.apply(&mut negative);
    println!("After when - positive: {}, negative: {}\n", positive, negative);

    // when().or_else() (conditional branching)
    let 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.apply(&mut positive);
    adjust.apply(&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 mutator = shared_clone;
        mutator.apply(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

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

    let thread_result = handle.join().expect("thread should not panic");
    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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

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

    // double and add_ten are still available
    let mut value3 = 10;
    let d = double;
    d.apply(&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 c1 = clone1;
    c1.apply(&mut value1);
    println!("clone1: 5 -> {}", value1);

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

    let mut value3 = 7;
    let c3 = rc_mutator;
    c3.apply(&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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

    let mut value2 = 5;
    let p2 = pipeline2;
    p2.apply(&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.apply(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 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.apply(&mut value1);
    println!("-50 -> {}", value1);

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

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

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

    let 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.apply(&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 box_mut = closure.into_box();
    let mut value = 5;
    box_mut.apply(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

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

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

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

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.apply(&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 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.apply(&mut point);
    println!("After processing: {:?}\n", point);

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

fn into_rc(self) -> RcMutator<T>

where Self: Sized + '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 qubit_function::Mutator;

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

Examples found in repository

examples/mutators/mutator_demo.rs (line 327)

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

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

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

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

    let 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.apply(&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 closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.apply(&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 noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.apply(&mut value);
    println!("After noop: {} (unchanged)\n", value);

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

    // when (conditional execution)
    let 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.apply(&mut positive);
    increment_if_positive.apply(&mut negative);
    println!("After when - positive: {}, negative: {}\n", positive, negative);

    // when().or_else() (conditional branching)
    let 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.apply(&mut positive);
    adjust.apply(&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 mutator = shared_clone;
        mutator.apply(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

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

    let thread_result = handle.join().expect("thread should not panic");
    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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

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

    // double and add_ten are still available
    let mut value3 = 10;
    let d = double;
    d.apply(&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 c1 = clone1;
    c1.apply(&mut value1);
    println!("clone1: 5 -> {}", value1);

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

    let mut value3 = 7;
    let c3 = rc_mutator;
    c3.apply(&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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

    let mut value2 = 5;
    let p2 = pipeline2;
    p2.apply(&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.apply(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 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.apply(&mut value1);
    println!("-50 -> {}", value1);

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

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

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

    let 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.apply(&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 box_mut = closure.into_box();
    let mut value = 5;
    box_mut.apply(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

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

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

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

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.apply(&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 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.apply(&mut point);
    println!("After processing: {:?}\n", point);

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

fn into_arc(self) -> ArcMutator<T>

where Self: Sized + Send + Sync + '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 qubit_function::Mutator;

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

Examples found in repository

examples/mutators/mutator_demo.rs (line 334)

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

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

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

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

    let 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.apply(&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 closure_chain = (|x: &mut i32| *x *= 2).and_then(|x: &mut i32| *x += 10);

    let mut value = 5;
    println!("Initial value: {}", value);
    closure_chain.apply(&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 noop = BoxMutator::<i32>::noop();
    let mut value = 42;
    println!("Before noop: {}", value);
    noop.apply(&mut value);
    println!("After noop: {} (unchanged)\n", value);

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

    // when (conditional execution)
    let 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.apply(&mut positive);
    increment_if_positive.apply(&mut negative);
    println!("After when - positive: {}, negative: {}\n", positive, negative);

    // when().or_else() (conditional branching)
    let 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.apply(&mut positive);
    adjust.apply(&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 mutator = shared_clone;
        mutator.apply(&mut value);
        println!("In thread: 5 * 2 = {}", value);
        value
    });

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

    let thread_result = handle.join().expect("thread should not panic");
    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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

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

    // double and add_ten are still available
    let mut value3 = 10;
    let d = double;
    d.apply(&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 c1 = clone1;
    c1.apply(&mut value1);
    println!("clone1: 5 -> {}", value1);

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

    let mut value3 = 7;
    let c3 = rc_mutator;
    c3.apply(&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.clone());
    let pipeline2 = add_ten.and_then(double.clone());

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

    let mut value2 = 5;
    let p2 = pipeline2;
    p2.apply(&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.apply(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 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.apply(&mut value1);
    println!("-50 -> {}", value1);

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

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

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

    let 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.apply(&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 box_mut = closure.into_box();
    let mut value = 5;
    box_mut.apply(&mut value);
    println!("Closure -> BoxMutator: 5 -> {}", value);

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

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

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

    // RcMutator -> BoxMutator
    let rc_mut = RcMutator::new(|x: &mut i32| *x *= 2);
    let box_mut = rc_mut.into_box();
    let mut value = 5;
    box_mut.apply(&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 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.apply(&mut point);
    println!("After processing: {:?}\n", point);

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

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

where Self: Sized + 'static,

Consume the mutator and return an Fn(&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 Fn(&mut T) which forwards to the original mutator.

Examples

use qubit_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 into_once(self) -> BoxMutatorOnce<T>

where Self: Sized + 'static,

Convert this mutator into a BoxMutatorOnce<T> (consuming).

This consuming conversion takes ownership of self and returns a boxed one-time mutator that forwards calls to the original mutator. The returned mutator can only be used once.

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 BoxMutatorOnce<T> that forwards to the original mutator.

Examples

use qubit_function::{Mutator, MutatorOnce, BoxMutator, BoxMutatorOnce};

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

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

where Self: Sized + Clone + '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,

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

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

The default implementation clones self (requires Clone + Send + Sync) 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 Fn(&mut T)

where Self: Sized + Clone + 'static,

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

fn to_once(&self) -> BoxMutatorOnce<T>

where Self: Sized + Clone + 'static,

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

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

Returns

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

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

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

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

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

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

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

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

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

where F: Fn(&mut T),