Trait Filterable

Source

pub trait Filterable: Compactable + Functor {
    // Provided methods
    fn partition_map<'a, A: 'a, E: 'a, O: 'a>(
        func: impl Fn(A) -> Result<O, E> + 'a,
        fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>,
    ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, E>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, O>) { ... }
    fn partition<'a, A: 'a + Clone>(
        func: impl Fn(A) -> bool + 'a,
        fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>,
    ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>) { ... }
    fn filter_map<'a, A: 'a, B: 'a>(
        func: impl Fn(A) -> Option<B> + 'a,
        fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>,
    ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, B> { ... }
    fn filter<'a, A: 'a + Clone>(
        func: impl Fn(A) -> bool + 'a,
        fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>,
    ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, A> { ... }
}

Expand description

A type class for data structures that can be filtered and partitioned.

Filterable extends Compactable and Functor, adding methods for:

filter: Keeping elements that satisfy a predicate.
filter_map: Mapping and filtering in one step.
partition: Splitting elements based on a predicate.
partition_map: Mapping and partitioning in one step.

§Laws

Filterable instances must satisfy the following laws:

Distributivity: filter_map(identity, fa) = compact(fa).
Distributivity: partition_map(identity, fa) = separate(fa).
Identity: filter_map(Some, fa) = fa.
Composition: filter_map(|a| r(a).and_then(l), fa) = filter_map(l, filter_map(r, fa)).
Consistency (filter/filter_map): filter(p, fa) = filter_map(|a| if p(a) { Some(a) } else { None }, fa).
Consistency (partition/partition_map): partition(p, fa) = partition_map(|a| if p(a) { Ok(a) } else { Err(a) }, fa).

§Examples

Filterable laws for Option:

use fp_library::{
	brands::*,
	functions::*,
};

// Distributivity: filter_map(identity, fa) = compact(fa)
let fa: Option<Option<i32>> = Some(Some(5));
assert_eq!(
	filter_map::<OptionBrand, _, _>(identity, fa),
	compact::<OptionBrand, _>(fa),
);

// Distributivity: partition_map(identity, fa) = separate(fa)
let fa: Option<Result<i32, &str>> = Some(Ok(5));
assert_eq!(
	partition_map::<OptionBrand, _, _, _>(identity, fa),
	separate::<OptionBrand, _, _>(fa),
);

// Identity: filter_map(Some, fa) = fa
assert_eq!(filter_map::<OptionBrand, _, _>(Some, Some(5)), Some(5));
assert_eq!(filter_map::<OptionBrand, _, _>(Some, None::<i32>), None);

// Composition: filter_map(|a| r(a).and_then(l), fa) = filter_map(l, filter_map(r, fa))
let l = |x: i32| if x > 3 { Some(x * 10) } else { None };
let r = |x: i32| if x > 1 { Some(x + 1) } else { None };
assert_eq!(
	filter_map::<OptionBrand, _, _>(|a| r(a).and_then(l), Some(5)),
	filter_map::<OptionBrand, _, _>(l, filter_map::<OptionBrand, _, _>(r, Some(5))),
);

// Consistency (filter/filter_map): filter(p, fa) = filter_map(|a| if p(a) { Some(a) } else { None }, fa)
let p = |x: i32| x > 3;
assert_eq!(
	filter::<OptionBrand, _>(p, Some(5)),
	filter_map::<OptionBrand, _, _>(|a: i32| if p(a) { Some(a) } else { None }, Some(5)),
);

Filterable laws for Vec:

use fp_library::{
	brands::*,
	functions::*,
};

// Distributivity: filter_map(identity, fa) = compact(fa)
let fa: Vec<Option<i32>> = vec![Some(1), None, Some(3)];
assert_eq!(
	filter_map::<VecBrand, _, _>(identity, fa.clone()),
	compact::<VecBrand, _>(fa),
);

// Identity: filter_map(Some, fa) = fa
assert_eq!(
	filter_map::<VecBrand, _, _>(Some, vec![1, 2, 3]),
	vec![1, 2, 3],
);

// Composition: filter_map(|a| r(a).and_then(l), fa) = filter_map(l, filter_map(r, fa))
let l = |x: i32| if x > 3 { Some(x * 10) } else { None };
let r = |x: i32| if x > 1 { Some(x + 1) } else { None };
assert_eq!(
	filter_map::<VecBrand, _, _>(|a| r(a).and_then(l), vec![1, 2, 3, 4, 5]),
	filter_map::<VecBrand, _, _>(l, filter_map::<VecBrand, _, _>(r, vec![1, 2, 3, 4, 5])),
);

// Consistency (filter/filter_map): filter(p, fa) = filter_map(|a| if p(a) { Some(a) } else { None }, fa)
let p = |x: i32| x > 3;
assert_eq!(
	filter::<VecBrand, _>(p, vec![1, 2, 3, 4, 5]),
	filter_map::<VecBrand, _, _>(|a: i32| if p(a) { Some(a) } else { None }, vec![1, 2, 3, 4, 5]),
);

§Minimal Implementation

A minimal implementation of Filterable requires no specific method implementations, as all methods have default implementations based on Compactable and Functor.

However, it is recommended to implement Filterable::partition_map and Filterable::filter_map to avoid the intermediate structure created by the default implementations (which use map followed by separate or compact).

If Filterable::partition_map is implemented, Filterable::partition is derived from it.
If Filterable::filter_map is implemented, Filterable::filter is derived from it.

Provided Methods§

Source

fn partition_map<'a, A: 'a, E: 'a, O: 'a>( func: impl Fn(A) -> Result<O, E> + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, E>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, O>)

Partitions a data structure based on a function that returns a Result.

The default implementation uses map and separate.

§Type Signature

forall A E O. (A -> Result O E, Self A) -> (Self E, Self O)

§Type Parameters

'a: The lifetime of the elements.
A: The type of the elements in the input structure.
E: The type of the error values.
O: The type of the success values.

§Parameters

func: The function to apply to each element, returning a Result.
fa: The data structure to partition.

§Returns

A pair of data structures: the first containing the Err values, and the second containing the Ok values.

§Examples

use fp_library::{
	brands::*,
	functions::*,
};

let x = Some(5);
let (errs, oks) =
	partition_map::<OptionBrand, _, _, _>(|a| if a > 2 { Ok(a) } else { Err(a) }, x);
assert_eq!(oks, Some(5));
assert_eq!(errs, None);

Source

fn partition<'a, A: 'a + Clone>( func: impl Fn(A) -> bool + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>)

Partitions a data structure based on a predicate.

The default implementation uses partition_map.

Note: The return order is (satisfied, not_satisfied), matching Rust’s Iterator::partition. This is achieved by mapping satisfied elements to Ok and unsatisfied elements to Err internally, as separate returns (Oks, Errs).

§Type Signature

forall A. (A -> bool, Self A) -> (Self A, Self A)

§Type Parameters

'a: The lifetime of the elements.
A: The type of the elements in the structure.

§Parameters

func: The predicate function.
fa: The data structure to partition.

§Returns

A pair of data structures: the first containing elements that do not satisfy the predicate, and the second containing elements that do.

§Examples

use fp_library::{
	brands::*,
	functions::*,
};

let x = Some(5);
let (not_satisfied, satisfied) = partition::<OptionBrand, _>(|a| a > 2, x);
assert_eq!(satisfied, Some(5));
assert_eq!(not_satisfied, None);

Source

fn filter_map<'a, A: 'a, B: 'a>( func: impl Fn(A) -> Option<B> + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, B>

Maps a function over a data structure and filters out None results.

The default implementation uses map and compact.

§Type Signature

forall A B. (A -> Option B, Self A) -> Self B

§Type Parameters

'a: The lifetime of the elements.
A: The type of the elements in the input structure.
B: The type of the elements in the output structure.

§Parameters

func: The function to apply to each element, returning an Option.
fa: The data structure to filter and map.

§Returns

A new data structure containing only the values where the function returned Some.

§Examples

use fp_library::{
	brands::*,
	functions::*,
};

let x = Some(5);
let y = filter_map::<OptionBrand, _, _>(|a| if a > 2 { Some(a * 2) } else { None }, x);
assert_eq!(y, Some(10));

Source

fn filter<'a, A: 'a + Clone>( func: impl Fn(A) -> bool + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>

Filters a data structure based on a predicate.

The default implementation uses filter_map.

§Type Signature

forall A. (A -> bool, Self A) -> Self A

§Type Parameters

'a: The lifetime of the elements.
A: The type of the elements in the structure.

§Parameters

func: The predicate function.
fa: The data structure to filter.

§Returns

A new data structure containing only the elements that satisfy the predicate.

§Examples

use fp_library::{
	brands::*,
	functions::*,
};

let x = Some(5);
let y = filter::<OptionBrand, _>(|a| a > 2, x);
assert_eq!(y, Some(5));

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§

Source §

impl Filterable for CatListBrand

Source §

impl Filterable for OptionBrand

Source §

Filterable

Trait Filterable Copy item path

§Laws

§Examples

§Minimal Implementation

Provided Methods§

fn partition_map<'a, A: 'a, E: 'a, O: 'a>( func: impl Fn(A) -> Result<O, E> + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, E>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, O>)

§Type Signature

§Type Parameters

§Parameters

§Returns

§Examples

fn partition<'a, A: 'a + Clone>( func: impl Fn(A) -> bool + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> (<Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>)

§Type Signature

§Type Parameters

§Parameters

§Returns

§Examples

fn filter_map<'a, A: 'a, B: 'a>( func: impl Fn(A) -> Option<B> + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, B>

§Type Signature

§Type Signature

§Type Parameters

§Parameters

§Returns

§Examples

fn filter<'a, A: 'a + Clone>( func: impl Fn(A) -> bool + 'a, fa: <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>, ) -> <Self as Kind_cdc7cd43dac7585f>::Of<'a, A>

§Type Signature

§Type Parameters

§Parameters

§Returns

§Examples

Dyn Compatibility§

Implementors§

impl Filterable for CatListBrand

impl Filterable for OptionBrand

impl Filterable for VecBrand

Trait Filterable