fp_library/types/

option.rs

use crate::{
	Apply,
	brands::OptionBrand,
	classes::{
		applicative::Applicative, apply_first::ApplyFirst, apply_second::ApplySecond,
		cloneable_fn::CloneableFn, compactable::Compactable, filterable::Filterable,
		foldable::Foldable, functor::Functor, lift::Lift, monoid::Monoid,
		par_foldable::ParFoldable, pointed::Pointed, semiapplicative::Semiapplicative,
		semimonad::Semimonad, send_cloneable_fn::SendCloneableFn, traversable::Traversable,
		witherable::Witherable,
	},
	impl_kind,
	kinds::*,
	types::Pair,
};

impl_kind! {
	for OptionBrand {
		type Of<'a, A: 'a>: 'a = Option<A>;
	}
}

impl Functor for OptionBrand {
	/// Maps a function over the value in the option.
	///
	/// This method applies a function to the value inside the option, producing a new option with the transformed value. If the option is `None`, it returns `None`.
	///
	/// ### Type Signature
	///
	/// `forall b a. Functor Option => (a -> b, Option a) -> Option b`
	///
	/// ### Type Parameters
	///
	/// * `B`: The type of the result of applying the function.
	/// * `A`: The type of the value inside the option.
	/// * `F`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `f`: The function to apply to the value.
	/// * `fa`: The option to map over.
	///
	/// ### Returns
	///
	/// A new option containing the result of applying the function, or `None`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(5);
	/// let y = map::<OptionBrand, _, _, _>(|i| i * 2, x);
	/// assert_eq!(y, Some(10));
	/// ```
	fn map<'a, B: 'a, A: 'a, F>(
		f: F,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>)
	where
		F: Fn(A) -> B + 'a,
	{
		fa.map(f)
	}
}

impl Lift for OptionBrand {
	/// Lifts a binary function into the option context.
	///
	/// This method lifts a binary function to operate on values within the option context.
	///
	/// ### Type Signature
	///
	/// `forall c a b. Lift Option => ((a, b) -> c, Option a, Option b) -> Option c`
	///
	/// ### Type Parameters
	///
	/// * `C`: The return type of the function.
	/// * `A`: The type of the first option's value.
	/// * `B`: The type of the second option's value.
	/// * `F`: The type of the binary function.
	///
	/// ### Parameters
	///
	/// * `f`: The binary function to apply.
	/// * `fa`: The first option.
	/// * `fb`: The second option.
	///
	/// ### Returns
	///
	/// `Some(f(a, b))` if both options are `Some`, otherwise `None`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(1);
	/// let y = Some(2);
	/// let z = lift2::<OptionBrand, _, _, _, _>(|a, b| a + b, x, y);
	/// assert_eq!(z, Some(3));
	/// ```
	fn lift2<'a, C, A, B, F>(
		f: F,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		fb: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>),
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, C>)
	where
		F: Fn(A, B) -> C + 'a,
		A: 'a,
		B: 'a,
		C: 'a,
	{
		fa.zip(fb).map(|(a, b)| f(a, b))
	}
}

impl Pointed for OptionBrand {
	/// Wraps a value in an option.
	///
	/// This method wraps a value in an option context.
	///
	/// ### Type Signature
	///
	/// `forall a. Pointed Option => a -> Option a`
	///
	/// ### Type Parameters
	///
	/// * `A`: The type of the value to wrap.
	///
	/// ### Parameters
	///
	/// * `a`: The value to wrap.
	///
	/// ### Returns
	///
	/// `Some(a)`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = pure::<OptionBrand, _>(5);
	/// assert_eq!(x, Some(5));
	/// ```
	fn pure<'a, A: 'a>(a: A) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
		Some(a)
	}
}

impl ApplyFirst for OptionBrand {}
impl ApplySecond for OptionBrand {}

impl Semiapplicative for OptionBrand {
	/// Applies a wrapped function to a wrapped value.
	///
	/// This method applies a function wrapped in an option to a value wrapped in an option.
	///
	/// ### Type Signature
	///
	/// `forall fn_brand b a. Semiapplicative Option => (Option (fn_brand a b), Option a) -> Option b`
	///
	/// ### Type Parameters
	///
	/// * `FnBrand`: The brand of the cloneable function wrapper.
	/// * `B`: The type of the output value.
	/// * `A`: The type of the input value.
	///
	/// ### Parameters
	///
	/// * `ff`: The option containing the function.
	/// * `fa`: The option containing the value.
	///
	/// ### Returns
	///
	/// `Some(f(a))` if both are `Some`, otherwise `None`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{brands::*, classes::*, functions::*};
	///
	/// let f = Some(cloneable_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2));
	/// let x = Some(5);
	/// let y = apply::<RcFnBrand, OptionBrand, _, _>(f, x);
	/// assert_eq!(y, Some(10));
	/// ```
	fn apply<'a, FnBrand: 'a + CloneableFn, B: 'a, A: 'a + Clone>(
		ff: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, <FnBrand as CloneableFn>::Of<'a, A, B>>),
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) {
		match (ff, fa) {
			(Some(f), Some(a)) => Some(f(a)),
			_ => None,
		}
	}
}

impl Semimonad for OptionBrand {
	/// Chains option computations.
	///
	/// This method chains two option computations, where the second computation depends on the result of the first.
	///
	/// ### Type Signature
	///
	/// `forall b a. Semimonad Option => (Option a, a -> Option b) -> Option b`
	///
	/// ### Type Parameters
	///
	/// * `B`: The type of the result of the second computation.
	/// * `A`: The type of the result of the first computation.
	/// * `F`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `ma`: The first option.
	/// * `f`: The function to apply to the value inside the option.
	///
	/// ### Returns
	///
	/// The result of applying `f` to the value if `ma` is `Some`, otherwise `None`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(5);
	/// let y = bind::<OptionBrand, _, _, _>(x, |i| Some(i * 2));
	/// assert_eq!(y, Some(10));
	/// ```
	fn bind<'a, B: 'a, A: 'a, F>(
		ma: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		f: F,
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>)
	where
		F: Fn(A) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) + 'a,
	{
		ma.and_then(f)
	}
}

impl Foldable for OptionBrand {
	/// Folds the option from the right.
	///
	/// This method performs a right-associative fold of the option. If the option is `Some(a)`, it applies the function to `a` and the initial value. If `None`, it returns the initial value.
	///
	/// ### Type Signature
	///
	/// `forall b a. Foldable Option => ((a, b) -> b, b, Option a) -> b`
	///
	/// ### Type Parameters
	///
	/// * `FnBrand`: The brand of the cloneable function to use.
	/// * `B`: The type of the accumulator.
	/// * `A`: The type of the elements in the structure.
	/// * `Func`: The type of the folding function.
	///
	/// ### Parameters
	///
	/// * `func`: The folding function.
	/// * `initial`: The initial value.
	/// * `fa`: The option to fold.
	///
	/// ### Returns
	///
	/// `func(a, initial)` if `fa` is `Some(a)`, otherwise `initial`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::{OptionBrand, RcFnBrand};
	///
	/// let x = Some(5);
	/// let y = fold_right::<RcFnBrand, OptionBrand, _, _, _>(|a, b| a + b, 10, x);
	/// assert_eq!(y, 15);
	/// ```
	fn fold_right<'a, FnBrand, B: 'a, A: 'a, Func>(
		func: Func,
		initial: B,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> B
	where
		Func: Fn(A, B) -> B + 'a,
		FnBrand: CloneableFn + 'a,
	{
		match fa {
			Some(a) => func(a, initial),
			None => initial,
		}
	}

	/// Folds the option from the left.
	///
	/// This method performs a left-associative fold of the option. If the option is `Some(a)`, it applies the function to the initial value and `a`. If `None`, it returns the initial value.
	///
	/// ### Type Signature
	///
	/// `forall b a. Foldable Option => ((b, a) -> b, b, Option a) -> b`
	///
	/// ### Type Parameters
	///
	/// * `FnBrand`: The brand of the cloneable function to use.
	/// * `B`: The type of the accumulator.
	/// * `A`: The type of the elements in the structure.
	/// * `Func`: The type of the folding function.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply to the accumulator and each element.
	/// * `initial`: The initial value of the accumulator.
	/// * `fa`: The option to fold.
	///
	/// ### Returns
	///
	/// `f(initial, a)` if `fa` is `Some(a)`, otherwise `initial`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::{OptionBrand, RcFnBrand};
	///
	/// let x = Some(5);
	/// let y = fold_left::<RcFnBrand, OptionBrand, _, _, _>(|b, a| b + a, 10, x);
	/// assert_eq!(y, 15);
	/// ```
	fn fold_left<'a, FnBrand, B: 'a, A: 'a, Func>(
		func: Func,
		initial: B,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> B
	where
		Func: Fn(B, A) -> B + 'a,
		FnBrand: CloneableFn + 'a,
	{
		match fa {
			Some(a) => func(initial, a),
			None => initial,
		}
	}

	/// Maps the value to a monoid and returns it, or returns empty.
	///
	/// This method maps the element of the option to a monoid. If the option is `None`, it returns the monoid's identity element.
	///
	/// ### Type Signature
	///
	/// `forall m a. (Foldable Option, Monoid m) => ((a) -> m, Option a) -> m`
	///
	/// ### Type Parameters
	///
	/// * `FnBrand`: The brand of the cloneable function to use.
	/// * `M`: The type of the monoid.
	/// * `A`: The type of the elements in the structure.
	/// * `Func`: The type of the mapping function.
	///
	/// ### Parameters
	///
	/// * `func`: The mapping function.
	/// * `fa`: The option to fold.
	///
	/// ### Returns
	///
	/// `func(a)` if `fa` is `Some(a)`, otherwise `M::empty()`.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{brands::*, functions::*, types::*};
	///
	/// let x = Some(5);
	/// let y = fold_map::<RcFnBrand, OptionBrand, _, _, _>(|a: i32| a.to_string(), x);
	/// assert_eq!(y, "5".to_string());
	/// ```
	fn fold_map<'a, FnBrand, M, A: 'a, Func>(
		func: Func,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> M
	where
		M: Monoid + 'a,
		Func: Fn(A) -> M + 'a,
		FnBrand: CloneableFn + 'a,
	{
		match fa {
			Some(a) => func(a),
			None => M::empty(),
		}
	}
}

impl Traversable for OptionBrand {
	/// Traverses the option with an applicative function.
	///
	/// This method maps the element of the option to a computation, evaluates it, and wraps the result in the applicative context. If `None`, it returns `pure(None)`.
	///
	/// ### Type Signature
	///
	/// `forall f b a. (Traversable Option, Applicative f) => (a -> f b, Option a) -> f (Option b)`
	///
	/// ### Type Parameters
	///
	/// * `F`: The applicative context.
	/// * `B`: The type of the elements in the resulting traversable structure.
	/// * `A`: The type of the elements in the traversable structure.
	/// * `Func`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply to each element, returning a value in an applicative context.
	/// * `ta`: The option to traverse.
	///
	/// ### Returns
	///
	/// The option wrapped in the applicative context.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(5);
	/// let y = traverse::<OptionBrand, OptionBrand, _, _, _>(|a| Some(a * 2), x);
	/// assert_eq!(y, Some(Some(10)));
	/// ```
	fn traverse<'a, F: Applicative, B: 'a + Clone, A: 'a + Clone, Func>(
		func: Func,
		ta: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>)>)
	where
		Func: Fn(A) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) + 'a,
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>): Clone,
	{
		match ta {
			Some(a) => F::map(|b| Some(b), func(a)),
			None => F::pure(None),
		}
	}
	/// Sequences an option of applicative.
	///
	/// This method evaluates the computation inside the option and wraps the result in the applicative context. If `None`, it returns `pure(None)`.
	///
	/// ### Type Signature
	///
	/// `forall f a. (Traversable Option, Applicative f) => (Option (f a)) -> f (Option a)`
	///
	/// ### Type Parameters
	///
	/// * `F`: The applicative context.
	/// * `A`: The type of the elements in the traversable structure.
	///
	/// ### Parameters
	///
	/// * `ta`: The option containing the applicative value.
	///
	/// # Returns
	///
	/// The option wrapped in the applicative context.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(Some(5));
	/// let y = sequence::<OptionBrand, OptionBrand, _>(x);
	/// assert_eq!(y, Some(Some(5)));
	/// ```
	fn sequence<'a, F: Applicative, A: 'a + Clone>(
		ta: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)>)
	) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)>)
	where
		Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>): Clone,
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>): Clone,
	{
		match ta {
			Some(fa) => F::map(|a| Some(a), fa),
			None => F::pure(None),
		}
	}
}

impl<FnBrand: SendCloneableFn> ParFoldable<FnBrand> for OptionBrand {
	/// Maps the value to a monoid and returns it, or returns empty, in parallel.
	///
	/// This method maps the element of the option to a monoid. Since `Option` contains at most one element, no actual parallelism occurs, but the interface is satisfied.
	///
	/// ### Type Signature
	///
	/// `forall fn_brand m a. (ParFoldable Option, Monoid m, Send m, Sync m) => (fn_brand a m, Option a) -> m`
	///
	/// ### Type Parameters
	///
	/// * `M`: The monoid type (must be `Send + Sync`).
	/// * `A`: The element type (must be `Send + Sync`).
	///
	/// ### Parameters
	///
	/// * `func`: The mapping function.
	/// * `fa`: The option to fold.
	///
	/// ### Returns
	///
	/// The combined monoid value.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::{OptionBrand, ArcFnBrand};
	///
	/// let x = Some(1);
	/// let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|x: i32| x.to_string());
	/// let y = par_fold_map::<ArcFnBrand, OptionBrand, _, _>(f, x);
	/// assert_eq!(y, "1".to_string());
	/// ```
	fn par_fold_map<'a, M, A>(
		func: <FnBrand as SendCloneableFn>::SendOf<'a, A, M>,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> M
	where
		A: 'a + Clone + Send + Sync,
		M: Monoid + Send + Sync + 'a,
	{
		match fa {
			Some(a) => func(a),
			None => M::empty(),
		}
	}
}

impl Compactable for OptionBrand {
	/// Compacts a nested option.
	///
	/// This method flattens a nested option.
	///
	/// ### Type Signature
	///
	/// `forall a. Compactable Option => Option (Option a) -> Option a`
	///
	/// ### Type Parameters
	///
	/// * `A`: The type of the elements.
	///
	/// ### Parameters
	///
	/// * `fa`: The nested option.
	///
	/// ### Returns
	///
	/// The flattened option.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(Some(5));
	/// let y = compact::<OptionBrand, _>(x);
	/// assert_eq!(y, Some(5));
	/// ```
	fn compact<'a, A: 'a>(
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<
			'a,
			Apply!(<OptionBrand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		>)
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
		fa.flatten()
	}

	/// Separates an option of result.
	///
	/// This method separates an option of result into a pair of options.
	///
	/// ### Type Signature
	///
	/// `forall o e. Compactable Option => Option (Result o e) -> (Option o, Option e)`
	///
	/// ### Type Parameters
	///
	/// * `O`: The type of the success value.
	/// * `E`: The type of the error value.
	///
	/// ### Parameters
	///
	/// * `fa`: The option of result.
	///
	/// ### Returns
	///
	/// A pair of options.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{brands::*, functions::*, types::*};
	///
	/// let x: Option<Result<i32, &str>> = Some(Ok(5));
	/// let Pair(oks, errs) = separate::<OptionBrand, _, _>(x);
	/// assert_eq!(oks, Some(5));
	/// assert_eq!(errs, None);
	/// ```
	fn separate<'a, O: 'a, E: 'a>(
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
	) -> Pair<
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
	> {
		match fa {
			Some(Ok(o)) => Pair(Some(o), None),
			Some(Err(e)) => Pair(None, Some(e)),
			None => Pair(None, None),
		}
	}
}

impl Filterable for OptionBrand {
	/// Partitions an option based on a function that returns a result.
	///
	/// This method partitions an option based on a function that returns a result.
	///
	/// ### Type Signature
	///
	/// `forall o e a. Filterable Option => (a -> Result o e, Option a) -> Pair (Option o) (Option e)`
	///
	/// ### Type Parameters
	///
	/// * `O`: The type of the success value.
	/// * `E`: The type of the error value.
	/// * `A`: The type of the input value.
	/// * `Func`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply.
	/// * `fa`: The option to partition.
	///
	/// ### Returns
	///
	/// A pair of options.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{brands::*, functions::*, types::*};
	///
	/// let x = Some(5);
	/// let Pair(oks, errs) = partition_map::<OptionBrand, _, _, _, _>(|a| if a > 2 { Ok(a) } else { Err(a) }, x);
	/// assert_eq!(oks, Some(5));
	/// assert_eq!(errs, None);
	/// ```
	fn partition_map<'a, O: 'a, E: 'a, A: 'a, Func>(
		func: Func,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Pair<
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
	>
	where
		Func: Fn(A) -> Result<O, E> + 'a,
	{
		match fa {
			Some(a) => match func(a) {
				Ok(o) => Pair(Some(o), None),
				Err(e) => Pair(None, Some(e)),
			},
			None => Pair(None, None),
		}
	}
	/// Partitions an option based on a predicate.
	///
	/// This method partitions an option based on a predicate.
	///
	/// ### Type Signature
	///
	/// `forall a. Filterable Option => (a -> bool, Option a) -> Pair (Option a) (Option a)`
	///
	/// ### Type Parameters
	///
	/// * `A`: The type of the elements.
	/// * `Func`: The type of the predicate.
	///
	/// ### Parameters
	///
	/// * `func`: The predicate.
	/// * `fa`: The option to partition.
	///
	/// ### Returns
	///
	/// A pair of options.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{brands::*, functions::*, types::*};
	///
	/// let x = Some(5);
	/// let Pair(satisfied, not_satisfied) = partition::<OptionBrand, _, _>(|a| a > 2, x);
	/// assert_eq!(satisfied, Some(5));
	/// assert_eq!(not_satisfied, None);
	/// ```
	fn partition<'a, A: 'a + Clone, Func>(
		func: Func,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Pair<
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	>
	where
		Func: Fn(A) -> bool + 'a,
	{
		match fa {
			Some(a) => {
				if func(a.clone()) {
					Pair(Some(a), None)
				} else {
					Pair(None, Some(a))
				}
			}
			None => Pair(None, None),
		}
	}

	/// Maps a function over an option and filters out `None` results.
	///
	/// This method maps a function over an option and filters out `None` results.
	///
	/// ### Type Signature
	///
	/// `forall b a. Filterable Option => (a -> Option b, Option a) -> Option b`
	///
	/// ### Type Parameters
	///
	/// * `B`: The type of the result of applying the function.
	/// * `A`: The type of the input value.
	/// * `Func`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply.
	/// * `fa`: The option to filter and map.
	///
	/// ### Returns
	///
	/// The filtered and mapped option.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(5);
	/// let y = filter_map::<OptionBrand, _, _, _>(|a| if a > 2 { Some(a * 2) } else { None }, x);
	/// assert_eq!(y, Some(10));
	/// ```
	fn filter_map<'a, B: 'a, A: 'a, Func>(
		func: Func,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>)
	where
		Func: Fn(A) -> Option<B> + 'a,
	{
		fa.and_then(func)
	}

	/// Filters an option based on a predicate.
	///
	/// This method filters an option based on a predicate.
	///
	/// ### Type Signature
	///
	/// `forall a. Filterable Option => (a -> bool, Option a) -> Option a`
	///
	/// ### Type Parameters
	///
	/// * `A`: The type of the elements.
	/// * `Func`: The type of the predicate.
	///
	/// ### Parameters
	///
	/// * `func`: The predicate.
	/// * `fa`: The option to filter.
	///
	/// ### Returns
	///
	/// The filtered option.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::functions::*;
	/// use fp_library::brands::OptionBrand;
	///
	/// let x = Some(5);
	/// let y = filter::<OptionBrand, _, _>(|a| a > 2, x);
	/// assert_eq!(y, Some(5));
	/// ```
	fn filter<'a, A: 'a + Clone, Func>(
		func: Func,
		fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
	where
		Func: Fn(A) -> bool + 'a,
	{
		fa.filter(|a| func(a.clone()))
	}
}

impl Witherable for OptionBrand {
	/// Partitions an option based on a function that returns a result in an applicative context.
	///
	/// This method partitions an option based on a function that returns a result in an applicative context.
	///
	/// ### Type Signature
	///
	/// `forall m o e a. (Witherable Option, Applicative m) => (a -> m (Result o e), Option a) -> m (Pair (Option o) (Option e))`
	///
	/// ### Type Parameters
	///
	/// * `M`: The applicative context.
	/// * `O`: The type of the success values.
	/// * `E`: The type of the error values.
	/// * `A`: The type of the elements in the input structure.
	/// * `Func`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply to each element, returning a `Result` in an applicative context.
	/// * `ta`: The option to partition.
	///
	/// ### Returns
	///
	/// The partitioned option wrapped in the applicative context.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{functions::*, brands::*, types::*};
	///
	/// let x = Some(5);
	/// let y = wilt::<OptionBrand, OptionBrand, _, _, _, _>(|a| Some(if a > 2 { Ok(a) } else { Err(a) }), x);
	/// assert_eq!(y, Some(Pair(Some(5), None)));
	/// ```
	fn wilt<'a, M: Applicative, O: 'a + Clone, E: 'a + Clone, A: 'a + Clone, Func>(
		func: Func,
		ta: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<
		'a,
		Pair<
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
		>,
	>)
	where
		Func: Fn(A) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>) + 'a,
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>): Clone,
		Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>): Clone,
	{
		match ta {
			Some(a) => M::map(
				|res| match res {
					Ok(o) => Pair(Some(o), None),
					Err(e) => Pair(None, Some(e)),
				},
				func(a),
			),
			None => M::pure(Pair(None, None)),
		}
	}

	/// Maps a function over an option and filters out `None` results in an applicative context.
	///
	/// This method maps a function over an option and filters out `None` results in an applicative context.
	///
	/// ### Type Signature
	///
	/// `forall m b a. (Witherable Option, Applicative m) => (a -> m (Option b), Option a) -> m (Option b)`
	///
	/// ### Type Parameters
	///
	/// * `M`: The applicative context.
	/// * `B`: The type of the result of applying the function.
	/// * `A`: The type of the elements in the input structure.
	/// * `Func`: The type of the function to apply.
	///
	/// ### Parameters
	///
	/// * `func`: The function to apply to each element, returning an `Option` in an applicative context.
	/// * `ta`: The option to filter and map.
	///
	/// ### Returns
	///
	/// The filtered and mapped option wrapped in the applicative context.
	///
	/// ### Examples
	///
	/// ```
	/// use fp_library::{functions::*, brands::*};
	///
	/// let x = Some(5);
	/// let y = wither::<OptionBrand, OptionBrand, _, _, _>(|a| Some(if a > 2 { Some(a * 2) } else { None }), x);
	/// assert_eq!(y, Some(Some(10)));
	/// ```
	fn wither<'a, M: Applicative, B: 'a + Clone, A: 'a + Clone, Func>(
		func: Func,
		ta: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
	) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<
		'a,
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>),
	>)
	where
		Func: Fn(A) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Option<B>>) + 'a,
		Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Option<B>>): Clone,
		Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Option<B>>): Clone,
	{
		match ta {
			Some(a) => func(a),
			None => M::pure(None),
		}
	}
}

#[cfg(test)]
mod tests {
	use super::*;
	use crate::{brands::*, functions::*};
	use quickcheck_macros::quickcheck;

	// Functor Laws

	/// Tests the identity law for Functor.
	#[quickcheck]
	fn functor_identity(x: Option<i32>) -> bool {
		map::<OptionBrand, _, _, _>(identity, x) == x
	}

	/// Tests the composition law for Functor.
	#[quickcheck]
	fn functor_composition(x: Option<i32>) -> bool {
		let f = |x: i32| x.wrapping_add(1);
		let g = |x: i32| x.wrapping_mul(2);
		map::<OptionBrand, _, _, _>(compose(f, g), x)
			== map::<OptionBrand, _, _, _>(f, map::<OptionBrand, _, _, _>(g, x))
	}

	// Applicative Laws

	/// Tests the identity law for Applicative.
	#[quickcheck]
	fn applicative_identity(v: Option<i32>) -> bool {
		apply::<RcFnBrand, OptionBrand, _, _>(
			pure::<OptionBrand, _>(<RcFnBrand as CloneableFn>::new(identity)),
			v,
		) == v
	}

	/// Tests the homomorphism law for Applicative.
	#[quickcheck]
	fn applicative_homomorphism(x: i32) -> bool {
		let f = |x: i32| x.wrapping_mul(2);
		apply::<RcFnBrand, OptionBrand, _, _>(
			pure::<OptionBrand, _>(<RcFnBrand as CloneableFn>::new(f)),
			pure::<OptionBrand, _>(x),
		) == pure::<OptionBrand, _>(f(x))
	}

	/// Tests the composition law for Applicative.
	#[quickcheck]
	fn applicative_composition(
		w: Option<i32>,
		u_is_some: bool,
		v_is_some: bool,
	) -> bool {
		let v_fn = |x: i32| x.wrapping_mul(2);
		let u_fn = |x: i32| x.wrapping_add(1);

		let v = if v_is_some {
			pure::<OptionBrand, _>(<RcFnBrand as CloneableFn>::new(v_fn))
		} else {
			None
		};
		let u = if u_is_some {
			pure::<OptionBrand, _>(<RcFnBrand as CloneableFn>::new(u_fn))
		} else {
			None
		};

		// RHS: u <*> (v <*> w)
		let vw = apply::<RcFnBrand, OptionBrand, _, _>(v.clone(), w.clone());
		let rhs = apply::<RcFnBrand, OptionBrand, _, _>(u.clone(), vw);

		// LHS: pure(compose) <*> u <*> v <*> w
		// equivalent to (u . v) <*> w
		let uv = match (u, v) {
			(Some(uf), Some(vf)) => {
				let composed = move |x| uf(vf(x));
				Some(<RcFnBrand as CloneableFn>::new(composed))
			}
			_ => None,
		};

		let lhs = apply::<RcFnBrand, OptionBrand, _, _>(uv, w);

		lhs == rhs
	}

	/// Tests the interchange law for Applicative.
	#[quickcheck]
	fn applicative_interchange(y: i32) -> bool {
		// u <*> pure y = pure ($ y) <*> u
		let f = |x: i32| x.wrapping_mul(2);
		let u = pure::<OptionBrand, _>(<RcFnBrand as CloneableFn>::new(f));

		let lhs = apply::<RcFnBrand, OptionBrand, _, _>(u.clone(), pure::<OptionBrand, _>(y));

		let rhs_fn =
			<RcFnBrand as CloneableFn>::new(move |f: std::rc::Rc<dyn Fn(i32) -> i32>| f(y));
		let rhs = apply::<RcFnBrand, OptionBrand, _, _>(pure::<OptionBrand, _>(rhs_fn), u);

		lhs == rhs
	}

	// Monad Laws

	/// Tests the left identity law for Monad.
	#[quickcheck]
	fn monad_left_identity(a: i32) -> bool {
		let f = |x: i32| Some(x.wrapping_mul(2));
		bind::<OptionBrand, _, _, _>(pure::<OptionBrand, _>(a), f) == f(a)
	}

	/// Tests the right identity law for Monad.
	#[quickcheck]
	fn monad_right_identity(m: Option<i32>) -> bool {
		bind::<OptionBrand, _, _, _>(m, pure::<OptionBrand, _>) == m
	}

	/// Tests the associativity law for Monad.
	#[quickcheck]
	fn monad_associativity(m: Option<i32>) -> bool {
		let f = |x: i32| Some(x.wrapping_mul(2));
		let g = |x: i32| Some(x.wrapping_add(1));
		bind::<OptionBrand, _, _, _>(bind::<OptionBrand, _, _, _>(m, f), g)
			== bind::<OptionBrand, _, _, _>(m, |x| bind::<OptionBrand, _, _, _>(f(x), g))
	}

	// Edge Cases

	/// Tests `map` on `None`.
	#[test]
	fn map_none() {
		assert_eq!(map::<OptionBrand, _, _, _>(|x: i32| x + 1, None), None);
	}

	/// Tests `bind` on `None`.
	#[test]
	fn bind_none() {
		assert_eq!(bind::<OptionBrand, _, _, _>(None, |x: i32| Some(x + 1)), None);
	}

	/// Tests `bind` returning `None`.
	#[test]
	fn bind_returning_none() {
		assert_eq!(bind::<OptionBrand, _, _, _>(Some(5), |_| None::<i32>), None);
	}

	/// Tests `fold_right` on `None`.
	#[test]
	fn fold_right_none() {
		assert_eq!(
			crate::classes::foldable::fold_right::<RcFnBrand, OptionBrand, _, _, _>(
				|x: i32, acc| x + acc,
				0,
				None
			),
			0
		);
	}

	/// Tests `fold_left` on `None`.
	#[test]
	fn fold_left_none() {
		assert_eq!(
			crate::classes::foldable::fold_left::<RcFnBrand, OptionBrand, _, _, _>(
				|acc, x: i32| acc + x,
				0,
				None
			),
			0
		);
	}

	/// Tests `traverse` on `None`.
	#[test]
	fn traverse_none() {
		assert_eq!(
			crate::classes::traversable::traverse::<OptionBrand, OptionBrand, _, _, _>(
				|x: i32| Some(x + 1),
				None
			),
			Some(None)
		);
	}

	/// Tests `traverse` returning `None`.
	#[test]
	fn traverse_returning_none() {
		assert_eq!(
			crate::classes::traversable::traverse::<OptionBrand, OptionBrand, _, _, _>(
				|_: i32| None::<i32>,
				Some(5)
			),
			None
		);
	}

	// ParFoldable Tests

	/// Tests `par_fold_map` on `None`.
	#[test]
	fn par_fold_map_none() {
		let x: Option<i32> = None;
		let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|x: i32| x.to_string());
		assert_eq!(par_fold_map::<ArcFnBrand, OptionBrand, _, _>(f, x), "".to_string());
	}

	/// Tests `par_fold_map` on `Some`.
	#[test]
	fn par_fold_map_some() {
		let x = Some(5);
		let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|x: i32| x.to_string());
		assert_eq!(par_fold_map::<ArcFnBrand, OptionBrand, _, _>(f, x), "5".to_string());
	}

	/// Tests `par_fold_right` on `Some`.
	#[test]
	fn par_fold_right_some() {
		let x = Some(5);
		let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|(a, b): (i32, i32)| a + b);
		assert_eq!(par_fold_right::<ArcFnBrand, OptionBrand, _, _>(f, 10, x), 15);
	}

	// Filterable Laws

	/// Tests `filterMap identity ≡ compact`.
	#[quickcheck]
	fn filterable_filter_map_identity(x: Option<Option<i32>>) -> bool {
		filter_map::<OptionBrand, _, _, _>(identity, x.clone()) == compact::<OptionBrand, _>(x)
	}

	/// Tests `filterMap Just ≡ identity`.
	#[quickcheck]
	fn filterable_filter_map_just(x: Option<i32>) -> bool {
		filter_map::<OptionBrand, _, _, _>(Some, x.clone()) == x
	}

	/// Tests `filterMap (l <=< r) ≡ filterMap l <<< filterMap r`.
	#[quickcheck]
	fn filterable_filter_map_composition(x: Option<i32>) -> bool {
		let r = |i: i32| if i % 2 == 0 { Some(i) } else { None };
		let l = |i: i32| if i > 5 { Some(i) } else { None };
		let composed = |i| r(i).and_then(l);

		filter_map::<OptionBrand, _, _, _>(composed, x.clone())
			== filter_map::<OptionBrand, _, _, _>(l, filter_map::<OptionBrand, _, _, _>(r, x))
	}

	/// Tests `filter ≡ filterMap <<< maybeBool`.
	#[quickcheck]
	fn filterable_filter_consistency(x: Option<i32>) -> bool {
		let p = |i: i32| i % 2 == 0;
		let maybe_bool = |i| if p(i) { Some(i) } else { None };

		filter::<OptionBrand, _, _>(p, x.clone())
			== filter_map::<OptionBrand, _, _, _>(maybe_bool, x)
	}

	/// Tests `partitionMap identity ≡ separate`.
	#[quickcheck]
	fn filterable_partition_map_identity(x: Option<Result<i32, i32>>) -> bool {
		partition_map::<OptionBrand, _, _, _, _>(identity, x.clone())
			== separate::<OptionBrand, _, _>(x)
	}

	/// Tests `partitionMap Right ≡ identity` (on the right side).
	#[quickcheck]
	fn filterable_partition_map_right_identity(x: Option<i32>) -> bool {
		let Pair(oks, _) = partition_map::<OptionBrand, _, _, _, _>(Ok::<_, i32>, x.clone());
		oks == x
	}

	/// Tests `partitionMap Left ≡ identity` (on the left side).
	#[quickcheck]
	fn filterable_partition_map_left_identity(x: Option<i32>) -> bool {
		let Pair(_, errs) = partition_map::<OptionBrand, _, _, _, _>(Err::<i32, _>, x.clone());
		errs == x
	}

	/// Tests `f <<< partition ≡ partitionMap <<< eitherBool`.
	#[quickcheck]
	fn filterable_partition_consistency(x: Option<i32>) -> bool {
		let p = |i: i32| i % 2 == 0;
		let either_bool = |i| if p(i) { Ok(i) } else { Err(i) };

		let Pair(satisfied, not_satisfied) = partition::<OptionBrand, _, _>(p, x.clone());
		let Pair(oks, errs) = partition_map::<OptionBrand, _, _, _, _>(either_bool, x);

		satisfied == oks && not_satisfied == errs
	}

	// Witherable Laws

	/// Tests `wither (pure <<< Just) ≡ pure`.
	#[quickcheck]
	fn witherable_identity(x: Option<i32>) -> bool {
		wither::<OptionBrand, OptionBrand, _, _, _>(|i| Some(Some(i)), x.clone()) == Some(x)
	}

	/// Tests `wilt p ≡ map separate <<< traverse p`.
	#[quickcheck]
	fn witherable_wilt_consistency(x: Option<i32>) -> bool {
		let p = |i: i32| Some(if i % 2 == 0 { Ok(i) } else { Err(i) });

		let lhs = wilt::<OptionBrand, OptionBrand, _, _, _, _>(p, x.clone());
		let rhs = map::<OptionBrand, _, _, _>(
			|res| separate::<OptionBrand, _, _>(res),
			traverse::<OptionBrand, OptionBrand, _, _, _>(p, x),
		);

		lhs == rhs
	}

	/// Tests `wither p ≡ map compact <<< traverse p`.
	#[quickcheck]
	fn witherable_wither_consistency(x: Option<i32>) -> bool {
		let p = |i: i32| Some(if i % 2 == 0 { Some(i) } else { None });

		let lhs = wither::<OptionBrand, OptionBrand, _, _, _>(p, x.clone());
		let rhs = map::<OptionBrand, _, _, _>(
			|opt| compact::<OptionBrand, _>(opt),
			traverse::<OptionBrand, OptionBrand, _, _, _>(p, x),
		);

		lhs == rhs
	}

	// Edge Cases

	/// Tests `compact` on `Some(None)`.
	#[test]
	fn compact_some_none() {
		assert_eq!(compact::<OptionBrand, _>(Some(None::<i32>)), None);
	}

	/// Tests `compact` on `Some(Some(x))`.
	#[test]
	fn compact_some_some() {
		assert_eq!(compact::<OptionBrand, _>(Some(Some(5))), Some(5));
	}

	/// Tests `compact` on `None`.
	#[test]
	fn compact_none() {
		assert_eq!(compact::<OptionBrand, _>(None::<Option<i32>>), None);
	}

	/// Tests `separate` on `Some(Ok(x))`.
	#[test]
	fn separate_some_ok() {
		let Pair(oks, errs) = separate::<OptionBrand, _, _>(Some(Ok::<i32, &str>(5)));
		assert_eq!(oks, Some(5));
		assert_eq!(errs, None);
	}

	/// Tests `separate` on `Some(Err(e))`.
	#[test]
	fn separate_some_err() {
		let Pair(oks, errs) = separate::<OptionBrand, _, _>(Some(Err::<i32, &str>("error")));
		assert_eq!(oks, None);
		assert_eq!(errs, Some("error"));
	}

	/// Tests `separate` on `None`.
	#[test]
	fn separate_none() {
		let Pair(oks, errs) = separate::<OptionBrand, _, _>(None::<Result<i32, &str>>);
		assert_eq!(oks, None);
		assert_eq!(errs, None);
	}

	/// Tests `partition_map` on `None`.
	#[test]
	fn partition_map_none() {
		let Pair(oks, errs) =
			partition_map::<OptionBrand, _, _, _, _>(|x: i32| Ok::<i32, i32>(x), None::<i32>);
		assert_eq!(oks, None);
		assert_eq!(errs, None);
	}

	/// Tests `partition` on `None`.
	#[test]
	fn partition_none() {
		let Pair(satisfied, not_satisfied) =
			partition::<OptionBrand, _, _>(|x: i32| x > 0, None::<i32>);
		assert_eq!(satisfied, None);
		assert_eq!(not_satisfied, None);
	}

	/// Tests `filter_map` on `None`.
	#[test]
	fn filter_map_none() {
		assert_eq!(filter_map::<OptionBrand, _, _, _>(|x: i32| Some(x), None::<i32>), None);
	}

	/// Tests `filter` on `None`.
	#[test]
	fn filter_none() {
		assert_eq!(filter::<OptionBrand, _, _>(|x: i32| x > 0, None::<i32>), None);
	}

	/// Tests `wilt` on `None`.
	#[test]
	fn wilt_none() {
		let res = wilt::<OptionBrand, OptionBrand, _, _, _, _>(
			|x: i32| Some(Ok::<i32, i32>(x)),
			None::<i32>,
		);
		assert_eq!(res, Some(Pair(None, None)));
	}

	/// Tests `wither` on `None`.
	#[test]
	fn wither_none() {
		let res = wither::<OptionBrand, OptionBrand, _, _, _>(|x: i32| Some(Some(x)), None::<i32>);
		assert_eq!(res, Some(None));
	}
}