Trait Predicate 

pub trait Predicate<T> {
    // Required method
    fn test(&self, value: &T) -> bool;

    // Provided methods
    fn into_box(self) -> BoxPredicate<T>
       where Self: Sized + 'static { ... }
    fn into_rc(self) -> RcPredicate<T>
       where Self: Sized + 'static { ... }
    fn into_arc(self) -> ArcPredicate<T>
       where Self: Sized + Send + Sync + 'static { ... }
    fn into_fn(self) -> impl Fn(&T) -> bool
       where Self: Sized + 'static { ... }
    fn to_box(&self) -> BoxPredicate<T>
       where Self: Clone + Sized + 'static { ... }
    fn to_rc(&self) -> RcPredicate<T>
       where Self: Clone + Sized + 'static { ... }
    fn to_arc(&self) -> ArcPredicate<T>
       where Self: Clone + Sized + Send + Sync + 'static { ... }
    fn to_fn(&self) -> impl Fn(&T) -> bool
       where Self: Clone + Sized + 'static { ... }
}

A predicate trait for testing whether a value satisfies a condition.

This trait represents a pure judgment operation - it tests whether a given value meets certain criteria without modifying either the value or the predicate itself (from the user’s perspective). This semantic clarity distinguishes predicates from consumers or transformers.

Design Rationale

This is a minimal trait that only defines:

• The core test method using &self (immutable borrow)
• Type conversion methods (into_box, into_rc, into_arc)
• Closure conversion method (into_fn)

Logical composition methods (and, or, not) are intentionally not part of the trait. Instead, they are implemented on concrete types (BoxPredicate, RcPredicate, ArcPredicate), allowing each implementation to maintain its specific ownership characteristics:

• BoxPredicate: Methods consume self (single ownership)
• RcPredicate: Methods borrow &self (shared ownership)
• ArcPredicate: Methods borrow &self (thread-safe shared ownership)

Why &self Instead of &mut self?

Predicates use &self because:

1. Semantic Clarity: A predicate is a judgment, not a mutation
2. Flexibility: Can be used in immutable contexts
3. Simplicity: No need for mut in user code
4. Interior Mutability: State (if needed) can be managed with RefCell, Cell, or Mutex

Automatic Implementation for Closures

Any closure matching Fn(&T) -> bool automatically implements this trait, providing seamless integration with Rust’s closure system.

Examples

Basic Usage

use qubit_function::Predicate;

let is_positive = |x: &i32| *x > 0;
assert!(is_positive.test(&5));
assert!(!is_positive.test(&-3));

Type Conversion

use qubit_function::{Predicate, BoxPredicate};

let closure = |x: &i32| *x > 0;
let boxed: BoxPredicate<i32> = closure.into_box();
assert!(boxed.test(&5));

Stateful Predicate with Interior Mutability

use qubit_function::{Predicate, BoxPredicate};
use std::cell::Cell;

let count = Cell::new(0);
let counting_pred = BoxPredicate::new(move |x: &i32| {
    count.set(count.get() + 1);
    *x > 0
});

// Note: No `mut` needed - interior mutability handles state
assert!(counting_pred.test(&5));
assert!(!counting_pred.test(&-3));

Author

Haixing Hu

Required Methods

fn test(&self, value: &T) -> bool

Tests whether the given value satisfies this predicate.

Parameters

• value - The value to test.

Returns

true if the value satisfies this predicate, false otherwise.

Provided Methods

fn into_box(self) -> BoxPredicate<T>

where Self: Sized + 'static,

Converts this predicate into a BoxPredicate.

The default implementation wraps the predicate in a closure that calls the test method. Concrete types may override this with more efficient implementations.

Returns

A BoxPredicate wrapping this predicate.

fn into_rc(self) -> RcPredicate<T>

where Self: Sized + 'static,

Converts this predicate into an RcPredicate.

The default implementation wraps the predicate in a closure that calls the test method. Concrete types may override this with more efficient implementations.

Returns

An RcPredicate wrapping this predicate.

fn into_arc(self) -> ArcPredicate<T>

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

Converts this predicate into an ArcPredicate.

The default implementation wraps the predicate in a closure that calls the test method. Concrete types may override this with more efficient implementations.

Returns

An ArcPredicate wrapping this predicate.

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

where Self: Sized + 'static,

Converts this predicate into a closure that can be used directly with standard library methods.

This method consumes the predicate and returns a closure with signature Fn(&T) -> bool. Since Fn is a subtrait of FnMut, the returned closure can be used in any context that requires either Fn(&T) -> bool or FnMut(&T) -> bool, making it compatible with methods like Iterator::filter, Iterator::filter_map, Vec::retain, and similar standard library APIs.

The default implementation returns a closure that calls the test method. Concrete types may override this with more efficient implementations.

Returns

A closure implementing Fn(&T) -> bool (also usable as FnMut(&T) -> bool).

Examples

Using with Iterator::filter (requires FnMut)

use qubit_function::{Predicate, BoxPredicate};

let pred = BoxPredicate::new(|x: &i32| *x > 0);

let numbers = vec![-2, -1, 0, 1, 2, 3];
let positives: Vec<_> = numbers.iter()
    .copied()
    .filter(pred.into_fn())
    .collect();
assert_eq!(positives, vec![1, 2, 3]);

Using with Vec::retain (requires FnMut)

use qubit_function::{Predicate, BoxPredicate};

let pred = BoxPredicate::new(|x: &i32| *x % 2 == 0);
let mut numbers = vec![1, 2, 3, 4, 5, 6];
numbers.retain(pred.into_fn());
assert_eq!(numbers, vec![2, 4, 6]);

Examples found in repository

examples/predicates/predicate_fn_mut_demo.rs (line 34)

fn demo_with_iterator_filter() {
    println!("1. Using Iterator::filter");

    let pred = BoxPredicate::new(|x: &i32| *x > 0);
    let numbers = vec![-2, -1, 0, 1, 2, 3];
    let positives: Vec<_> = numbers.iter().copied().filter(pred.into_fn()).collect();
    println!("   Original data: {:?}", numbers);
    println!("   Filtered result: {:?}", positives);
    assert_eq!(positives, vec![1, 2, 3]);
    println!("   ✓ BoxPredicate::into_fn() can be used in filter\n");
}

/// Demonstrates usage with Vec::retain (retain requires FnMut)
fn demo_with_vec_retain() {
    println!("2. Using Vec::retain");

    // RcPredicate example
    let pred = RcPredicate::new(|x: &i32| *x % 2 == 0);
    let mut numbers = vec![1, 2, 3, 4, 5, 6];
    println!("   Original data: {:?}", numbers);
    numbers.retain(pred.to_fn());
    println!("   Retained even numbers: {:?}", numbers);
    assert_eq!(numbers, vec![2, 4, 6]);

    // Original predicate is still available
    assert!(pred.test(&10));
    println!("   ✓ RcPredicate::to_fn() can be used in retain");
    println!("   ✓ Original predicate is still available\n");
}

/// Demonstrates usage with generic functions that require FnMut
fn demo_with_generic_function() {
    println!("3. Using generic functions (requires FnMut)");

    fn count_matching<F>(items: &[i32], mut predicate: F) -> usize
    where
        F: FnMut(&i32) -> bool,
    {
        items.iter().filter(|x| predicate(x)).count()
    }

    let pred = RcPredicate::new(|x: &i32| *x > 10);
    let count1 = count_matching(&[5, 15, 8, 20], pred.to_fn());
    println!("   First call: count = {}", count1);
    assert_eq!(count1, 2);

    // Original predicate can be reused
    let count2 = count_matching(&[12, 3, 18], pred.to_fn());
    println!("   Second call: count = {}", count2);
    assert_eq!(count2, 2);

    println!("   ✓ RcPredicate::to_fn() can be passed to generic functions requiring FnMut");
    println!("   ✓ Original predicate can be converted and used multiple times\n");
}

/// Demonstrates thread-safe usage
fn demo_thread_safe() {
    println!("4. Thread-safe usage");

    let pred = ArcPredicate::new(|x: &i32| *x > 0);
    // clone and convert into a 'static closure so it can be moved to another thread
    let closure = pred.clone().into_fn();

    // Closure can be passed between threads
    let handle = std::thread::spawn(move || {
        let numbers = [-2, -1, 0, 1, 2, 3];
        numbers.iter().copied().filter(closure).count()
    });

    let count = handle.join().unwrap();
    println!("   Filtered result count in thread: {}", count);
    assert_eq!(count, 3);

    // Original predicate is still available
    assert!(pred.test(&5));
    println!("   ✓ ArcPredicate::to_fn() returns a thread-safe closure");
    println!("   ✓ Original predicate is still available in main thread\n");
}

examples/predicates/always_predicate_demo.rs (line 141)

fn main() {
    println!("=== BoxPredicate always_true/always_false Demo ===\n");

    // BoxPredicate::always_true
    let always_true: BoxPredicate<i32> = BoxPredicate::always_true();
    println!("BoxPredicate::always_true():");
    println!("  test(&42): {}", always_true.test(&42));
    println!("  test(&-1): {}", always_true.test(&-1));
    println!("  test(&0): {}", always_true.test(&0));
    println!("  name: {:?}", always_true.name());

    // BoxPredicate::always_false
    let always_false: BoxPredicate<i32> = BoxPredicate::always_false();
    println!("\nBoxPredicate::always_false():");
    println!("  test(&42): {}", always_false.test(&42));
    println!("  test(&-1): {}", always_false.test(&-1));
    println!("  test(&0): {}", always_false.test(&0));
    println!("  name: {:?}", always_false.name());

    println!("\n=== RcPredicate always_true/always_false Demo ===\n");

    // RcPredicate::always_true
    let rc_always_true: RcPredicate<String> = RcPredicate::always_true();
    println!("RcPredicate::always_true():");
    println!(
        "  test(&\"hello\"): {}",
        rc_always_true.test(&"hello".to_string())
    );
    println!(
        "  test(&\"world\"): {}",
        rc_always_true.test(&"world".to_string())
    );
    println!("  name: {:?}", rc_always_true.name());

    // RcPredicate::always_false
    let rc_always_false: RcPredicate<String> = RcPredicate::always_false();
    println!("\nRcPredicate::always_false():");
    println!(
        "  test(&\"hello\"): {}",
        rc_always_false.test(&"hello".to_string())
    );
    println!(
        "  test(&\"world\"): {}",
        rc_always_false.test(&"world".to_string())
    );
    println!("  name: {:?}", rc_always_false.name());

    // Can be cloned and reused
    let rc_clone = rc_always_true.clone();
    println!("\nAfter cloning, still usable:");
    println!(
        "  Original: test(&\"test\"): {}",
        rc_always_true.test(&"test".to_string())
    );
    println!(
        "  Clone: test(&\"test\"): {}",
        rc_clone.test(&"test".to_string())
    );

    println!("\n=== ArcPredicate always_true/always_false Demo ===\n");

    // ArcPredicate::always_true
    let arc_always_true: ArcPredicate<i32> = ArcPredicate::always_true();
    println!("ArcPredicate::always_true():");
    println!("  test(&100): {}", arc_always_true.test(&100));
    println!("  test(&-100): {}", arc_always_true.test(&-100));
    println!("  name: {:?}", arc_always_true.name());

    // ArcPredicate::always_false
    let arc_always_false: ArcPredicate<i32> = ArcPredicate::always_false();
    println!("\nArcPredicate::always_false():");
    println!("  test(&100): {}", arc_always_false.test(&100));
    println!("  test(&-100): {}", arc_always_false.test(&-100));
    println!("  name: {:?}", arc_always_false.name());

    println!("\n=== Combining with other predicates ===\n");

    // Combining with always_true (AND)
    let is_positive = BoxPredicate::new(|x: &i32| *x > 0);
    let combined_and_true = is_positive.and(BoxPredicate::always_true());
    println!("is_positive AND always_true:");
    println!(
        "  test(&5): {} (equivalent to is_positive)",
        combined_and_true.test(&5)
    );
    println!(
        "  test(&-3): {} (equivalent to is_positive)",
        combined_and_true.test(&-3)
    );

    // Combining with always_false (AND)
    let is_positive = BoxPredicate::new(|x: &i32| *x > 0);
    let combined_and_false = is_positive.and(BoxPredicate::always_false());
    println!("\nis_positive AND always_false:");
    println!("  test(&5): {} (always false)", combined_and_false.test(&5));
    println!(
        "  test(&-3): {} (always false)",
        combined_and_false.test(&-3)
    );

    // Combining with always_true (OR)
    let is_positive = BoxPredicate::new(|x: &i32| *x > 0);
    let combined_or_true = is_positive.or(BoxPredicate::always_true());
    println!("\nis_positive OR always_true:");
    println!("  test(&5): {} (always true)", combined_or_true.test(&5));
    println!("  test(&-3): {} (always true)", combined_or_true.test(&-3));

    // Combining with always_false (OR)
    let is_positive = BoxPredicate::new(|x: &i32| *x > 0);
    let combined_or_false = is_positive.or(BoxPredicate::always_false());
    println!("\nis_positive OR always_false:");
    println!(
        "  test(&5): {} (equivalent to is_positive)",
        combined_or_false.test(&5)
    );
    println!(
        "  test(&-3): {} (equivalent to is_positive)",
        combined_or_false.test(&-3)
    );

    println!("\n=== Practical scenarios: Default pass/reject filters ===\n");

    // Scenario 1: Default pass-all filter
    let numbers = vec![1, 2, 3, 4, 5];
    let pass_all = BoxPredicate::<i32>::always_true();
    let filtered: Vec<_> = numbers.iter().copied().filter(pass_all.into_fn()).collect();
    println!("Default pass all elements: {:?} -> {:?}", numbers, filtered);

    // Scenario 2: Default reject-all filter
    let numbers = vec![1, 2, 3, 4, 5];
    let reject_all = BoxPredicate::<i32>::always_false();
    let filtered: Vec<_> = numbers
        .iter()
        .copied()
        .filter(reject_all.into_fn())
        .collect();
    println!(
        "Default reject all elements: {:?} -> {:?}",
        numbers, filtered
    );

    // Scenario 3: Configurable filter
    fn configurable_filter(enable_filter: bool) -> BoxPredicate<i32> {
        if enable_filter {
            BoxPredicate::new(|x: &i32| *x > 3)
        } else {
            BoxPredicate::always_true()
        }
    }

    let numbers = vec![1, 2, 3, 4, 5];

    let filter_enabled = configurable_filter(true);
    let filtered: Vec<_> = numbers
        .iter()
        .copied()
        .filter(filter_enabled.into_fn())
        .collect();
    println!("\nFilter enabled: {:?} -> {:?}", numbers, filtered);

    let filter_disabled = configurable_filter(false);
    let filtered: Vec<_> = numbers
        .iter()
        .copied()
        .filter(filter_disabled.into_fn())
        .collect();
    println!("Filter disabled: {:?} -> {:?}", numbers, filtered);
}

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

where Self: Clone + Sized + 'static,

Converts a reference to this predicate into a BoxPredicate.

This method clones the predicate and then converts it to a BoxPredicate. The original predicate remains usable after this call.

Returns

A BoxPredicate wrapping a clone of this predicate.

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

where Self: Clone + Sized + 'static,

Converts a reference to this predicate into an RcPredicate.

This method clones the predicate and then converts it to an RcPredicate. The original predicate remains usable after this call.

Returns

An RcPredicate wrapping a clone of this predicate.

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

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

Converts a reference to this predicate into an ArcPredicate.

This method clones the predicate and then converts it to an ArcPredicate. The original predicate remains usable after this call.

Returns

An ArcPredicate wrapping a clone of this predicate.

fn to_fn(&self) -> impl Fn(&T) -> bool

where Self: Clone + Sized + 'static,

Converts a reference to this predicate into a closure that can be used directly with standard library methods.

This method clones the predicate and then converts it to a closure. The original predicate remains usable after this call.

The returned closure has signature Fn(&T) -> bool. Since Fn is a subtrait of FnMut, it can be used in any context that requires either Fn(&T) -> bool or FnMut(&T) -> bool, making it compatible with methods like Iterator::filter, Iterator::filter_map, Vec::retain, and similar standard library APIs.

Returns

A closure implementing Fn(&T) -> bool (also usable as FnMut(&T) -> bool).

Examples found in repository

examples/predicates/predicate_fn_mut_demo.rs (line 49)

fn demo_with_vec_retain() {
    println!("2. Using Vec::retain");

    // RcPredicate example
    let pred = RcPredicate::new(|x: &i32| *x % 2 == 0);
    let mut numbers = vec![1, 2, 3, 4, 5, 6];
    println!("   Original data: {:?}", numbers);
    numbers.retain(pred.to_fn());
    println!("   Retained even numbers: {:?}", numbers);
    assert_eq!(numbers, vec![2, 4, 6]);

    // Original predicate is still available
    assert!(pred.test(&10));
    println!("   ✓ RcPredicate::to_fn() can be used in retain");
    println!("   ✓ Original predicate is still available\n");
}

/// Demonstrates usage with generic functions that require FnMut
fn demo_with_generic_function() {
    println!("3. Using generic functions (requires FnMut)");

    fn count_matching<F>(items: &[i32], mut predicate: F) -> usize
    where
        F: FnMut(&i32) -> bool,
    {
        items.iter().filter(|x| predicate(x)).count()
    }

    let pred = RcPredicate::new(|x: &i32| *x > 10);
    let count1 = count_matching(&[5, 15, 8, 20], pred.to_fn());
    println!("   First call: count = {}", count1);
    assert_eq!(count1, 2);

    // Original predicate can be reused
    let count2 = count_matching(&[12, 3, 18], pred.to_fn());
    println!("   Second call: count = {}", count2);
    assert_eq!(count2, 2);

    println!("   ✓ RcPredicate::to_fn() can be passed to generic functions requiring FnMut");
    println!("   ✓ Original predicate can be converted and used multiple times\n");
}

Implementors

impl<T> Predicate<T> for ArcPredicate<T>

impl<T> Predicate<T> for BoxPredicate<T>

impl<T> Predicate<T> for RcPredicate<T>

impl<T, F> Predicate<T> for F

where F: Fn(&T) -> bool,