Skip to main content

ConsumerOnce

qubit_function::consumers::consumer_once

Trait ConsumerOnce 

Source 
pub trait ConsumerOnce<T> {
    // Required method
    fn accept(self, value: &T);

    // Provided methods
    fn into_box(self) -> BoxConsumerOnce<T>
       where Self: Sized + 'static { ... }
    fn into_fn(self) -> impl FnOnce(&T)
       where Self: Sized + 'static { ... }
    fn to_box(&self) -> BoxConsumerOnce<T>
       where Self: Sized + Clone + 'static { ... }
    fn to_fn(&self) -> impl FnOnce(&T)
       where Self: Sized + Clone + 'static { ... }
}
Expand description

ConsumerOnce trait - Unified one-time consumer interface

It is similar to the FnOnce(&T) trait in the standard library.

Defines the core behavior of all one-time consumer types. Similar to consumers implementing FnOnce(&T), executes operations that accept a value reference but return no result (only side effects), consuming itself in the process.

§Automatic Implementation

  • All closures implementing FnOnce(&T)
  • BoxConsumerOnce<T>

§Features

  • Unified Interface: All consumer types share the same accept method signature
  • Automatic Implementation: Closures automatically implement this trait with zero overhead
  • Type Conversion: Can be converted to BoxConsumerOnce
  • Generic Programming: Write functions that work with any one-time consumer type

§Examples

use qubit_function::{ConsumerOnce, BoxConsumerOnce};
use std::sync::{Arc, Mutex};

fn apply_consumer<C: ConsumerOnce<i32>>(consumer: C, value: &i32) {
    consumer.accept(value);
}

let log = Arc::new(Mutex::new(Vec::new()));
let l = log.clone();
let box_con = BoxConsumerOnce::new(move |x: &i32| {
    l.lock().expect("mutex should not be poisoned").push(*x);
});
apply_consumer(box_con, &5);
assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![5]);

Required Methods§

Source

fn accept(self, value: &T)

Execute one-time consumption operation

Executes an operation on the given reference. The operation typically reads the input value or produces side effects, but does not modify the input value itself. Consumes self.

§Parameters
  • value - Reference to the value to be consumed
§Examples
use qubit_function::{ConsumerOnce, BoxConsumerOnce};

let consumer = BoxConsumerOnce::new(|x: &i32| println!("{}", x));
consumer.accept(&5);

Provided Methods§

Source

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

Convert to BoxConsumerOnce

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

§Default Implementation

The default implementation wraps self in a BoxConsumerOnce by calling accept on the consumer. Types can override this method to provide more efficient conversions.

§Returns

Returns the wrapped BoxConsumerOnce<T>

§Examples
use qubit_function::ConsumerOnce;
use std::sync::{Arc, Mutex};

let log = Arc::new(Mutex::new(Vec::new()));
let l = log.clone();
let closure = move |x: &i32| {
    l.lock().expect("mutex should not be poisoned").push(*x);
};
let box_consumer = closure.into_box();
box_consumer.accept(&5);
assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![5]);
Examples found in repository?
examples/consumers/consumer_once_demo.rs (line 148)
24fn main() {
25    println!("=== ConsumerOnce Demo ===\n");
26
27    // 1. BoxConsumerOnce - Single ownership, one-time use
28    println!("1. BoxConsumerOnce - Single ownership");
29    {
30        let log = Arc::new(Mutex::new(Vec::new()));
31        let l = log.clone();
32        let consumer = BoxConsumerOnce::new(move |x: &i32| {
33            l.lock().expect("mutex should not be poisoned").push(*x);
34            println!("  BoxConsumerOnce consumed: {}", x);
35        });
36        consumer.accept(&42);
37        println!("  Log: {:?}\n", *log.lock().expect("mutex should not be poisoned"));
38    }
39
40    // 2. BoxConsumerOnce - Method chaining
41    println!("2. BoxConsumerOnce - Method chaining");
42    {
43        let log = Arc::new(Mutex::new(Vec::new()));
44        let l1 = log.clone();
45        let l2 = log.clone();
46        let l3 = log.clone();
47        let chained = BoxConsumerOnce::new(move |x: &i32| {
48            l1.lock().expect("mutex should not be poisoned").push(*x * 2);
49            println!("  Step 1: {} * 2 = {}", x, x * 2);
50        })
51        .and_then(move |x: &i32| {
52            l2.lock().expect("mutex should not be poisoned").push(*x + 10);
53            println!("  Step 2: {} + 10 = {}", x, x + 10);
54        })
55        .and_then(move |x: &i32| {
56            l3.lock().expect("mutex should not be poisoned").push(*x - 1);
57            println!("  Step 3: {} - 1 = {}", x, x - 1);
58        });
59        chained.accept(&5);
60        println!("  Log: {:?}\n", *log.lock().expect("mutex should not be poisoned"));
61    }
62
63    // 3. BoxConsumerOnce - Factory methods
64    println!("3. BoxConsumerOnce - Factory methods");
65    {
66        // No-op consumer
67        let noop = BoxConsumerOnce::<i32>::noop();
68        noop.accept(&42);
69        println!("  No-op consumer executed (no output)");
70
71        // Print consumer
72        print!("  Print consumer: ");
73        let print = BoxConsumerOnce::new(|x: &i32| println!("{}", x));
74        print.accept(&42);
75
76        // Print with prefix
77        print!("  Print with prefix: ");
78        let print_with = BoxConsumerOnce::new(|x: &i32| println!("Value: {}", x));
79        print_with.accept(&42);
80
81        // Conditional consumer
82        let log = Arc::new(Mutex::new(Vec::new()));
83        let l = log.clone();
84        let conditional = BoxConsumerOnce::new(move |x: &i32| {
85            l.lock().expect("mutex should not be poisoned").push(*x * 2);
86        })
87        .when(|x: &i32| *x > 0);
88        conditional.accept(&5);
89        println!(
90            "  Conditional (positive): {:?}",
91            *log.lock().expect("mutex should not be poisoned")
92        );
93
94        let log = Arc::new(Mutex::new(Vec::new()));
95        let l = log.clone();
96        let conditional = BoxConsumerOnce::new(move |x: &i32| {
97            l.lock().expect("mutex should not be poisoned").push(*x * 2);
98        })
99        .when(|x: &i32| *x > 0);
100        conditional.accept(&-5);
101        println!(
102            "  Conditional (negative): {:?}\n",
103            *log.lock().expect("mutex should not be poisoned")
104        );
105    }
106
107    // 4. Closure usage
108    println!("4. Closure usage");
109    {
110        let log = Arc::new(Mutex::new(Vec::new()));
111        let l = log.clone();
112        let closure = move |x: &i32| {
113            l.lock().expect("mutex should not be poisoned").push(*x * 2);
114            println!("  Closure consumed: {}", x);
115        };
116        closure.accept(&42);
117        println!("  Log: {:?}\n", *log.lock().expect("mutex should not be poisoned"));
118    }
119
120    // 5. Closure chaining
121    println!("5. Closure chaining");
122    {
123        let log = Arc::new(Mutex::new(Vec::new()));
124        let l1 = log.clone();
125        let l2 = log.clone();
126        let chained = (move |x: &i32| {
127            l1.lock().expect("mutex should not be poisoned").push(*x * 2);
128            println!("  Closure 1: {} * 2 = {}", x, x * 2);
129        })
130        .and_then(move |x: &i32| {
131            l2.lock().expect("mutex should not be poisoned").push(*x + 10);
132            println!("  Closure 2: {} + 10 = {}", x, x + 10);
133        });
134        chained.accept(&5);
135        println!("  Log: {:?}\n", *log.lock().expect("mutex should not be poisoned"));
136    }
137
138    // 6. Type conversions
139    println!("6. Type conversions");
140    {
141        let log = Arc::new(Mutex::new(Vec::new()));
142
143        // Closure to BoxConsumerOnce
144        let l = log.clone();
145        let closure = move |x: &i32| {
146            l.lock().expect("mutex should not be poisoned").push(*x);
147        };
148        let box_consumer = closure.into_box();
149        box_consumer.accept(&1);
150        println!(
151            "  BoxConsumerOnce: {:?}",
152            *log.lock().expect("mutex should not be poisoned")
153        );
154    }
155
156    // 7. Using with iterators (BoxConsumerOnce)
157    println!("7. Using with iterators");
158    {
159        let log = Arc::new(Mutex::new(Vec::new()));
160        let l = log.clone();
161        let consumer = BoxConsumerOnce::new(move |x: &i32| {
162            l.lock().expect("mutex should not be poisoned").push(*x * 2);
163        });
164        // Note: This will panic because BoxConsumerOnce can only be called once
165        // vec![1, 2, 3, 4, 5].iter().for_each(consumer.into_fn());
166        consumer.accept(&1);
167        println!(
168            "  BoxConsumerOnce with single value: {:?}\n",
169            *log.lock().expect("mutex should not be poisoned")
170        );
171    }
172
173    println!("=== Demo Complete ===");
174}
Source

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

Convert to closure

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

Converts a one-time consumer to a closure that can be used directly in places where the standard library requires FnOnce.

§Default Implementation

The default implementation creates a closure that captures self and calls its accept method. Types can override this method to provide more efficient conversions.

§Returns

Returns a closure implementing FnOnce(&T)

§Examples
use qubit_function::ConsumerOnce;
use std::sync::{Arc, Mutex};

let log = Arc::new(Mutex::new(Vec::new()));
let l = log.clone();
let closure = move |x: &i32| {
    l.lock().expect("mutex should not be poisoned").push(*x * 2);
};
let func = closure.into_fn();
func(&5);
assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![10]);
Source

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

Convert to BoxConsumerOnce without consuming self

⚠️ Requires Clone: This method requires Self to implement Clone. Clones the current consumer and wraps it in a BoxConsumerOnce.

§Default Implementation

The default implementation clones self and then calls into_box() on the clone. Types can override this method to provide more efficient conversions.

§Returns

Returns the wrapped BoxConsumerOnce<T>

§Examples
use qubit_function::ConsumerOnce;
use std::sync::{Arc, Mutex};

let log = Arc::new(Mutex::new(Vec::new()));
let l = log.clone();
let closure = move |x: &i32| {
    l.lock().expect("mutex should not be poisoned").push(*x);
};
let box_consumer = closure.to_box();
box_consumer.accept(&5);
assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![5]);
Source

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

Convert to closure without consuming self

⚠️ Requires Clone: This method requires Self to implement Clone. Clones the current consumer and then converts the clone to a closure.

§Default Implementation

The default implementation clones self and then calls into_fn() on the clone. Types can override this method to provide more efficient conversions.

§Returns

Returns a closure implementing FnOnce(&T)

§Examples
use qubit_function::ConsumerOnce;
use std::sync::{Arc, Mutex};

let log = Arc::new(Mutex::new(Vec::new()));
let l = log.clone();
let closure = move |x: &i32| {
    l.lock().expect("mutex should not be poisoned").push(*x * 2);
};
let func = closure.to_fn();
func(&5);
assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![10]);

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§