Trait StatefulTransformer 

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

    // Provided methods
    fn into_box(self) -> BoxStatefulTransformer<T, R>
       where Self: Sized + 'static { ... }
    fn into_rc(self) -> RcStatefulTransformer<T, R>
       where Self: Sized + 'static { ... }
    fn into_arc(self) -> ArcStatefulTransformer<T, R>
       where Self: Sized + Send + 'static { ... }
    fn into_fn(self) -> impl FnMut(T) -> R
       where Self: Sized + 'static { ... }
    fn into_mut_fn(self) -> impl FnMut(T) -> R
       where Self: Sized + 'static { ... }
    fn into_once(self) -> BoxTransformerOnce<T, R>
       where Self: Sized + 'static { ... }
    fn to_box(&self) -> BoxStatefulTransformer<T, R>
       where Self: Sized + Clone + 'static { ... }
    fn to_rc(&self) -> RcStatefulTransformer<T, R>
       where Self: Sized + Clone + 'static { ... }
    fn to_arc(&self) -> ArcStatefulTransformer<T, R>
       where Self: Sized + Clone + Send + 'static { ... }
    fn to_fn(&self) -> impl FnMut(T) -> R
       where Self: Sized + Clone + 'static { ... }
    fn to_mut_fn(&self) -> impl FnMut(T) -> R
       where Self: Sized + Clone + 'static { ... }
    fn to_once(&self) -> BoxTransformerOnce<T, R>
       where Self: Sized + Clone + 'static { ... }
}

StatefulTransformer trait - transforms values from type T to type R with state

Defines the behavior of a stateful transformation: converting a value of type T to a value of type R by consuming the input while allowing modification of internal state. This is analogous to FnMut(T) -> R in Rust’s standard library.

Type Parameters

• T - The type of the input value (consumed)
• R - The type of the output value

Author

Haixing Hu

Required Methods

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

Applies the transformation to the input value to produce an output value

Parameters

• input - The input value to transform (consumed)

Returns

The transformed output value

Provided Methods

fn into_box(self) -> BoxStatefulTransformer<T, R>

where Self: Sized + 'static,

Converts to BoxStatefulTransformer

⚠️ Consumes self: The original transformer becomes unavailable after calling this method.

Returns

Returns BoxStatefulTransformer<T, R>

Default Implementation

The default implementation wraps self in a BoxStatefulTransformer by creating a new closure that calls self.apply(). This is a lightweight adapter, but it is not strictly zero-cost.

Examples

use qubit_function::{StatefulTransformer, BoxStatefulTransformer};

struct CustomTransformer {
    multiplier: i32,
}

impl StatefulTransformer<i32, i32> for CustomTransformer {
    fn apply(&mut self, input: i32) -> i32 {
        self.multiplier += 1;
        input * self.multiplier
    }
}

let transformer = CustomTransformer { multiplier: 0 };
let mut boxed = transformer.into_box();
assert_eq!(boxed.apply(10), 10);  // 10 * 1
assert_eq!(boxed.apply(10), 20);  // 10 * 2

Examples found in repository

examples/transformers/stateful_transformer_demo.rs (line 194)

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

    // 1. Basic BoxStatefulTransformer with state
    println!("1. BoxStatefulTransformer with stateful counter:");
    let mut counter = 0;
    let mut mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        format!("Item #{}: {}", counter, x)
    });

    println!("  {}", mapper.apply(100)); // Item #1: 100
    println!("  {}", mapper.apply(200)); // Item #2: 200
    println!("  {}", mapper.apply(300)); // Item #3: 300

    // 2. Composing mappers with and_then
    println!("\n2. Composing mappers with and_then:");
    let mut counter1 = 0;
    let mapper1 = BoxStatefulTransformer::new(move |x: i32| {
        counter1 += 1;
        x + counter1
    });

    let mut counter2 = 0;
    let mapper2 = BoxStatefulTransformer::new(move |x: i32| {
        counter2 += 1;
        x * counter2
    });

    let mut composed = mapper1.and_then(mapper2);
    println!("  First call:  {}", composed.apply(10)); // (10 + 1) * 1 = 11
    println!("  Second call: {}", composed.apply(10)); // (10 + 2) * 2 = 24
    println!("  Third call:  {}", composed.apply(10)); // (10 + 3) * 3 = 39

    // 3. Conditional mapping with when/or_else
    println!("\n3. Conditional mapping:");
    let mut high_count = 0;
    let mut low_count = 0;

    let mut conditional = BoxStatefulTransformer::new(move |x: i32| {
        high_count += 1;
        format!("High[{}]: {} * 2 = {}", high_count, x, x * 2)
    })
    .when(|x: &i32| *x >= 10)
    .or_else(move |x| {
        low_count += 1;
        format!("Low[{}]: {} + 1 = {}", low_count, x, x + 1)
    });

    println!("  {}", conditional.apply(15)); // High[1]: 15 * 2 = 30
    println!("  {}", conditional.apply(5)); // Low[1]: 5 + 1 = 6
    println!("  {}", conditional.apply(20)); // High[2]: 20 * 2 = 40

    // 4. RcStatefulTransformer for cloneable mappers
    println!("\n4. RcStatefulTransformer (cloneable, single-threaded):");
    let mut counter = 0;
    let mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x + counter
    });

    let mut mapper1 = mapper.clone();
    let mut mapper2 = mapper.clone();

    println!("  mapper1: {}", mapper1.apply(10)); // 11
    println!("  mapper2: {}", mapper2.apply(10)); // 12
    println!("  mapper1: {}", mapper1.apply(10)); // 13

    // 5. ArcStatefulTransformer for thread-safe mappers
    println!("\n5. ArcStatefulTransformer (thread-safe):");
    let mut counter = 0;
    let mapper = ArcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        format!("Result[{}]: {}", counter, x * 2)
    });

    let mut mapper_clone = mapper.clone();
    println!("  Original: {}", mapper_clone.apply(5)); // Result[1]: 10
    println!("  Clone:    {}", mapper_clone.apply(7)); // Result[2]: 14

    // 6. Using FnStatefulTransformerOps extension trait
    println!("\n6. Using FnStatefulTransformerOps extension trait:");
    let mut count = 0;
    let mut mapper = (move |x: i32| {
        count += 1;
        x + count
    })
    .and_then(|x| x * 2);

    println!("  {}", mapper.apply(10)); // (10 + 1) * 2 = 22
    println!("  {}", mapper.apply(10)); // (10 + 2) * 2 = 24

    // 7. Building a complex pipeline
    println!("\n7. Complex processing pipeline:");
    let mut step1_count = 0;
    let step1 = BoxStatefulTransformer::new(move |x: i32| {
        step1_count += 1;
        format!("Step1[{}]: {}", step1_count, x)
    });

    let mut step2_count = 0;
    let step2 = BoxStatefulTransformer::new(move |s: String| {
        step2_count += 1;
        format!("{} -> Step2[{}]", s, step2_count)
    });

    let mut step3_count = 0;
    let step3 = BoxStatefulTransformer::new(move |s: String| {
        step3_count += 1;
        format!("{} -> Step3[{}]", s, step3_count)
    });

    let mut pipeline = step1.and_then(step2).and_then(step3);

    println!("  {}", pipeline.apply(100));
    println!("  {}", pipeline.apply(200));

    // 7. TransformerOnce implementation - consuming transformers
    println!("\n7. TransformerOnce implementation - consuming StatefulTransformers:");

    // BoxStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut box_mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    println!(
        "  BoxStatefulTransformer consumed once: {}",
        box_mapper.apply(10)
    ); // 10 * 1 = 10

    // RcStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut rc_mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x + counter
    });
    let rc_clone = rc_mapper.clone(); // Clone before consuming
    println!(
        "  RcStatefulTransformer consumed once: {}",
        rc_mapper.apply(10)
    ); // 10 + 1 = 11
    println!("  RcStatefulTransformer clone still works: {}", {
        let mut rc_clone_for_call = rc_clone.clone();
        rc_clone_for_call.apply(10)
    }); // 10 + 2 = 12

    // ArcStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut arc_mapper = ArcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let arc_clone = arc_mapper.clone(); // Clone before consuming
    println!(
        "  ArcStatefulTransformer consumed once: {}",
        arc_mapper.apply(10)
    ); // 10 * 1 = 10
    println!("  ArcStatefulTransformer clone still works: {}", {
        let mut arc_clone_for_call = arc_clone.clone();
        arc_clone_for_call.apply(10)
    }); // 10 * 2 = 20

    // 8. Converting to BoxTransformerOnce
    println!("\n8. Converting StatefulTransformers to BoxTransformerOnce:");

    let mut counter = 0;
    let mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let mut once_mapper = mapper.into_box();
    println!(
        "  BoxStatefulTransformer->BoxTransformerOnce: {}",
        once_mapper.apply(5)
    ); // 5 * 1 = 5

    // RcStatefulTransformer can use to_box() to preserve original
    let mut counter = 0;
    let rc_mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let mut once_mapper = rc_mapper.to_box();
    println!(
        "  RcStatefulTransformer->BoxTransformerOnce: {}",
        once_mapper.apply(5)
    ); // 5 * 1 = 5
    println!("  Original RcStatefulTransformer still works: {}", {
        let mut rc_original_for_call = rc_mapper.clone();
        rc_original_for_call.apply(5)
    }); // 5 * 2 = 10

    println!("\n=== Demo Complete ===");
}

fn into_rc(self) -> RcStatefulTransformer<T, R>

where Self: Sized + 'static,

Converts to RcStatefulTransformer

⚠️ Consumes self: The original transformer becomes unavailable after calling this method.

Returns

Returns RcStatefulTransformer<T, R>

Default Implementation

The default implementation first converts to BoxStatefulTransformer using into_box(), then wraps it in RcStatefulTransformer. Specific implementations may override this for better efficiency.

Examples

use qubit_function::{StatefulTransformer, RcStatefulTransformer};

struct CustomTransformer {
    multiplier: i32,
}

impl StatefulTransformer<i32, i32> for CustomTransformer {
    fn apply(&mut self, input: i32) -> i32 {
        self.multiplier += 1;
        input * self.multiplier
    }
}

let transformer = CustomTransformer { multiplier: 0 };
let mut rc_transformer = transformer.into_rc();
assert_eq!(rc_transformer.apply(10), 10);  // 10 * 1
assert_eq!(rc_transformer.apply(10), 20);  // 10 * 2

fn into_arc(self) -> ArcStatefulTransformer<T, R>

where Self: Sized + Send + 'static,

Converts to ArcStatefulTransformer

⚠️ Consumes self: The original transformer becomes unavailable after calling this method.

Returns

Returns ArcStatefulTransformer<T, R>

Default Implementation

The default implementation wraps self in an ArcStatefulTransformer by creating a new closure that calls self.apply(). Note that this requires self to implement Send due to Arc’s thread-safety requirements.

Examples

use qubit_function::{StatefulTransformer, ArcStatefulTransformer};

struct CustomTransformer {
    multiplier: i32,
}

impl StatefulTransformer<i32, i32> for CustomTransformer {
    fn apply(&mut self, input: i32) -> i32 {
        self.multiplier += 1;
        input * self.multiplier
    }
}

let transformer = CustomTransformer { multiplier: 0 };
let mut arc_transformer = transformer.into_arc();
assert_eq!(arc_transformer.apply(10), 10);  // 10 * 1
assert_eq!(arc_transformer.apply(10), 20);  // 10 * 2

fn into_fn(self) -> impl FnMut(T) -> R

where Self: Sized + 'static,

Converts to a closure implementing FnMut(T) -> R

⚠️ Consumes self: The original transformer becomes unavailable after calling this method.

Returns

Returns an implementation of FnMut(T) -> R

Default Implementation

The default implementation creates a new closure that calls self.apply(). Specific implementations may override this for better efficiency.

Examples

use qubit_function::{StatefulTransformer, BoxStatefulTransformer};

let transformer = BoxStatefulTransformer::new(|x: i32| x * 2);
let mut closure = transformer.into_fn();
assert_eq!(closure(10), 20);
assert_eq!(closure(15), 30);

fn into_mut_fn(self) -> impl FnMut(T) -> R

where Self: Sized + 'static,

Converts transformer to a mutable closure (FnMut) with an explicit method name.

This is a naming alias of StatefulTransformer::into_fn to make the mutability of the returned closure explicit.

fn into_once(self) -> BoxTransformerOnce<T, R>

where Self: Sized + 'static,

Converts to BoxTransformerOnce.

This method has a default implementation that wraps the transformer in a BoxTransformerOnce. Custom implementations can override this method for optimization purposes.

Returns

A new BoxTransformerOnce<T, R> instance

Examples

use qubit_function::{StatefulTransformer, TransformerOnce};

let closure = |x: i32| x * 2;
let once = closure.into_once();
assert_eq!(once.apply(5), 10);

fn to_box(&self) -> BoxStatefulTransformer<T, R>

where Self: Sized + Clone + 'static,

Non-consuming conversion to BoxStatefulTransformer.

Default implementation requires Self: Clone and wraps a cloned instance in a RefCell so the returned transformer can mutate state across calls.

Examples found in repository

examples/transformers/stateful_transformer_demo.rs (line 206)

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

    // 1. Basic BoxStatefulTransformer with state
    println!("1. BoxStatefulTransformer with stateful counter:");
    let mut counter = 0;
    let mut mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        format!("Item #{}: {}", counter, x)
    });

    println!("  {}", mapper.apply(100)); // Item #1: 100
    println!("  {}", mapper.apply(200)); // Item #2: 200
    println!("  {}", mapper.apply(300)); // Item #3: 300

    // 2. Composing mappers with and_then
    println!("\n2. Composing mappers with and_then:");
    let mut counter1 = 0;
    let mapper1 = BoxStatefulTransformer::new(move |x: i32| {
        counter1 += 1;
        x + counter1
    });

    let mut counter2 = 0;
    let mapper2 = BoxStatefulTransformer::new(move |x: i32| {
        counter2 += 1;
        x * counter2
    });

    let mut composed = mapper1.and_then(mapper2);
    println!("  First call:  {}", composed.apply(10)); // (10 + 1) * 1 = 11
    println!("  Second call: {}", composed.apply(10)); // (10 + 2) * 2 = 24
    println!("  Third call:  {}", composed.apply(10)); // (10 + 3) * 3 = 39

    // 3. Conditional mapping with when/or_else
    println!("\n3. Conditional mapping:");
    let mut high_count = 0;
    let mut low_count = 0;

    let mut conditional = BoxStatefulTransformer::new(move |x: i32| {
        high_count += 1;
        format!("High[{}]: {} * 2 = {}", high_count, x, x * 2)
    })
    .when(|x: &i32| *x >= 10)
    .or_else(move |x| {
        low_count += 1;
        format!("Low[{}]: {} + 1 = {}", low_count, x, x + 1)
    });

    println!("  {}", conditional.apply(15)); // High[1]: 15 * 2 = 30
    println!("  {}", conditional.apply(5)); // Low[1]: 5 + 1 = 6
    println!("  {}", conditional.apply(20)); // High[2]: 20 * 2 = 40

    // 4. RcStatefulTransformer for cloneable mappers
    println!("\n4. RcStatefulTransformer (cloneable, single-threaded):");
    let mut counter = 0;
    let mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x + counter
    });

    let mut mapper1 = mapper.clone();
    let mut mapper2 = mapper.clone();

    println!("  mapper1: {}", mapper1.apply(10)); // 11
    println!("  mapper2: {}", mapper2.apply(10)); // 12
    println!("  mapper1: {}", mapper1.apply(10)); // 13

    // 5. ArcStatefulTransformer for thread-safe mappers
    println!("\n5. ArcStatefulTransformer (thread-safe):");
    let mut counter = 0;
    let mapper = ArcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        format!("Result[{}]: {}", counter, x * 2)
    });

    let mut mapper_clone = mapper.clone();
    println!("  Original: {}", mapper_clone.apply(5)); // Result[1]: 10
    println!("  Clone:    {}", mapper_clone.apply(7)); // Result[2]: 14

    // 6. Using FnStatefulTransformerOps extension trait
    println!("\n6. Using FnStatefulTransformerOps extension trait:");
    let mut count = 0;
    let mut mapper = (move |x: i32| {
        count += 1;
        x + count
    })
    .and_then(|x| x * 2);

    println!("  {}", mapper.apply(10)); // (10 + 1) * 2 = 22
    println!("  {}", mapper.apply(10)); // (10 + 2) * 2 = 24

    // 7. Building a complex pipeline
    println!("\n7. Complex processing pipeline:");
    let mut step1_count = 0;
    let step1 = BoxStatefulTransformer::new(move |x: i32| {
        step1_count += 1;
        format!("Step1[{}]: {}", step1_count, x)
    });

    let mut step2_count = 0;
    let step2 = BoxStatefulTransformer::new(move |s: String| {
        step2_count += 1;
        format!("{} -> Step2[{}]", s, step2_count)
    });

    let mut step3_count = 0;
    let step3 = BoxStatefulTransformer::new(move |s: String| {
        step3_count += 1;
        format!("{} -> Step3[{}]", s, step3_count)
    });

    let mut pipeline = step1.and_then(step2).and_then(step3);

    println!("  {}", pipeline.apply(100));
    println!("  {}", pipeline.apply(200));

    // 7. TransformerOnce implementation - consuming transformers
    println!("\n7. TransformerOnce implementation - consuming StatefulTransformers:");

    // BoxStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut box_mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    println!(
        "  BoxStatefulTransformer consumed once: {}",
        box_mapper.apply(10)
    ); // 10 * 1 = 10

    // RcStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut rc_mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x + counter
    });
    let rc_clone = rc_mapper.clone(); // Clone before consuming
    println!(
        "  RcStatefulTransformer consumed once: {}",
        rc_mapper.apply(10)
    ); // 10 + 1 = 11
    println!("  RcStatefulTransformer clone still works: {}", {
        let mut rc_clone_for_call = rc_clone.clone();
        rc_clone_for_call.apply(10)
    }); // 10 + 2 = 12

    // ArcStatefulTransformer can be consumed as TransformerOnce
    let mut counter = 0;
    let mut arc_mapper = ArcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let arc_clone = arc_mapper.clone(); // Clone before consuming
    println!(
        "  ArcStatefulTransformer consumed once: {}",
        arc_mapper.apply(10)
    ); // 10 * 1 = 10
    println!("  ArcStatefulTransformer clone still works: {}", {
        let mut arc_clone_for_call = arc_clone.clone();
        arc_clone_for_call.apply(10)
    }); // 10 * 2 = 20

    // 8. Converting to BoxTransformerOnce
    println!("\n8. Converting StatefulTransformers to BoxTransformerOnce:");

    let mut counter = 0;
    let mapper = BoxStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let mut once_mapper = mapper.into_box();
    println!(
        "  BoxStatefulTransformer->BoxTransformerOnce: {}",
        once_mapper.apply(5)
    ); // 5 * 1 = 5

    // RcStatefulTransformer can use to_box() to preserve original
    let mut counter = 0;
    let rc_mapper = RcStatefulTransformer::new(move |x: i32| {
        counter += 1;
        x * counter
    });
    let mut once_mapper = rc_mapper.to_box();
    println!(
        "  RcStatefulTransformer->BoxTransformerOnce: {}",
        once_mapper.apply(5)
    ); // 5 * 1 = 5
    println!("  Original RcStatefulTransformer still works: {}", {
        let mut rc_original_for_call = rc_mapper.clone();
        rc_original_for_call.apply(5)
    }); // 5 * 2 = 10

    println!("\n=== Demo Complete ===");
}

fn to_rc(&self) -> RcStatefulTransformer<T, R>

where Self: Sized + Clone + 'static,

Non-consuming conversion to RcStatefulTransformer.

Default implementation clones self into an Rc<RefCell<_>> so the resulting transformer can be shared within a single thread.

fn to_arc(&self) -> ArcStatefulTransformer<T, R>

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

Non-consuming conversion to ArcStatefulTransformer (thread-safe).

Default implementation requires Self: Clone + Send + Sync and wraps the cloned instance in Arc<Mutex<_>> so it can be used across threads.

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

where Self: Sized + Clone + 'static,

Non-consuming conversion to a closure (FnMut(T) -> R).

Default implementation clones self into a RefCell and returns a closure that calls apply on the interior mutable value.

fn to_mut_fn(&self) -> impl FnMut(T) -> R

where Self: Sized + Clone + 'static,

Non-consuming conversion to a mutable closure (FnMut) with an explicit method name.

This is a naming alias of StatefulTransformer::to_fn and preserves the same clone-based behavior.

fn to_once(&self) -> BoxTransformerOnce<T, R>

where Self: Sized + Clone + 'static,

Creates a BoxTransformerOnce from a cloned transformer

Uses Clone to obtain an owned copy and converts it into a BoxTransformerOnce. Requires Self: Clone. Custom implementations can override this for better performance.

Implementors

impl<T, R> StatefulTransformer<T, R> for ArcStatefulTransformer<T, R>

impl<T, R> StatefulTransformer<T, R> for BoxStatefulTransformer<T, R>

impl<T, R> StatefulTransformer<T, R> for RcStatefulTransformer<T, R>

impl<T, R, F> StatefulTransformer<T, R> for F

where F: FnMut(T) -> R,