fp_library/types/

identity.rs

//! Trivial wrapper that contains a single value.
//!
//! The simplest possible container type, often used as a base case for higher-kinded types or when a container is required but no additional effect is needed.

#[fp_macros::document_module]
mod inner {
	use {
		crate::{
			Apply,
			brands::IdentityBrand,
			classes::{
				Applicative,
				ApplyFirst,
				ApplySecond,
				CloneableFn,
				Foldable,
				Functor,
				Lift,
				Monoid,
				ParFoldable,
				Pointed,
				Semiapplicative,
				Semimonad,
				SendCloneableFn,
				Traversable,
			},
			impl_kind,
			kinds::*,
		},
		fp_macros::*,
	};

	/// Wraps a value.
	///
	/// The `Identity` type represents a trivial wrapper around a value. It is the simplest possible container.
	/// It is often used as a base case for higher-kinded types or when a container is required but no additional effect is needed.
	///
	/// ### Higher-Kinded Type Representation
	///
	/// The higher-kinded representation of this type constructor is [`IdentityBrand`](crate::brands::IdentityBrand),
	/// which is fully polymorphic over the wrapped value type.
	///
	/// ### Serialization
	///
	/// This type supports serialization and deserialization via [`serde`](https://serde.rs) when the `serde` feature is enabled.
	#[document_type_parameters("The type of the wrapped value.")]
	///
	#[document_fields("The wrapped value.")]
	///
	#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
	#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
	pub struct Identity<A>(pub A);

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

	#[document_type_parameters("The type of the wrapped value.")]
	#[document_parameters("The identity instance.")]
	impl<A> Identity<A> {
		/// Maps a function over the value in the identity.
		///
		/// This is the inherent version of [`Functor::map`], accepting
		/// `FnOnce` instead of `Fn` since it consumes `self`.
		#[document_signature]
		///
		#[document_type_parameters("The type of the result of applying the function.")]
		///
		#[document_parameters("The function to apply.")]
		///
		#[document_returns("A new identity containing the result of applying the function.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(5);
		/// let y = x.map(|i| i * 2);
		/// assert_eq!(y, Identity(10));
		/// ```
		pub fn map<B>(
			self,
			f: impl FnOnce(A) -> B,
		) -> Identity<B> {
			Identity(f(self.0))
		}

		/// Lifts a binary function to operate on two identities.
		///
		/// See [`Lift::lift2`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters(
			"The type of the other identity's value.",
			"The return type of the function."
		)]
		///
		#[document_parameters("The other identity.", "The binary function to apply.")]
		///
		#[document_returns("A new identity containing the result of applying the function.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(1);
		/// let y = Identity(2);
		/// let z = x.lift2(y, |a, b| a + b);
		/// assert_eq!(z, Identity(3));
		/// ```
		pub fn lift2<B, C>(
			self,
			other: Identity<B>,
			f: impl FnOnce(A, B) -> C,
		) -> Identity<C> {
			Identity(f(self.0, other.0))
		}

		/// Applies a wrapped function to a value.
		///
		/// See [`Semiapplicative::apply`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters("The return type of the wrapped function.")]
		///
		#[document_parameters("The identity containing the function.")]
		///
		#[document_returns("A new identity containing the result.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let f = Identity(|x: i32| x * 2);
		/// let x = Identity(5);
		/// let y = x.apply(f);
		/// assert_eq!(y, Identity(10));
		/// ```
		pub fn apply<B>(
			self,
			ff: Identity<impl FnOnce(A) -> B>,
		) -> Identity<B> {
			Identity(ff.0(self.0))
		}

		/// Chains identity computations.
		///
		/// This is the inherent version of [`Semimonad::bind`], accepting
		/// `FnOnce` instead of `Fn` since it consumes `self`.
		#[document_signature]
		///
		#[document_type_parameters("The type of the result of the chained computation.")]
		///
		#[document_parameters("The function to apply to the value inside the identity.")]
		///
		#[document_returns("The result of applying `f` to the value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(5);
		/// let y = x.bind(|i| Identity(i * 2));
		/// assert_eq!(y, Identity(10));
		/// ```
		pub fn bind<B>(
			self,
			f: impl FnOnce(A) -> Identity<B>,
		) -> Identity<B> {
			f(self.0)
		}

		/// Folds the identity from the right.
		///
		/// See [`Foldable::fold_right`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters("The type of the accumulator.")]
		///
		#[document_parameters(
			"The function to apply to the element and the accumulator.",
			"The initial value of the accumulator."
		)]
		///
		#[document_returns("The final accumulator value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(5);
		/// let y = x.fold_right(|a, b| a + b, 10);
		/// assert_eq!(y, 15);
		/// ```
		pub fn fold_right<B>(
			self,
			f: impl FnOnce(A, B) -> B,
			initial: B,
		) -> B {
			f(self.0, initial)
		}

		/// Folds the identity from the left.
		///
		/// See [`Foldable::fold_left`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters("The type of the accumulator.")]
		///
		#[document_parameters(
			"The function to apply to the accumulator and the element.",
			"The initial value of the accumulator."
		)]
		///
		#[document_returns("The final accumulator value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(5);
		/// let y = x.fold_left(|b, a| b + a, 10);
		/// assert_eq!(y, 15);
		/// ```
		pub fn fold_left<B>(
			self,
			f: impl FnOnce(B, A) -> B,
			initial: B,
		) -> B {
			f(initial, self.0)
		}

		/// Maps the value to a monoid and returns it.
		///
		/// See [`Foldable::fold_map`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters("The monoid type.")]
		///
		#[document_parameters("The mapping function.")]
		///
		#[document_returns("The monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::types::*;
		///
		/// let x = Identity(5);
		/// let y = x.fold_map(|a: i32| a.to_string());
		/// assert_eq!(y, "5".to_string());
		/// ```
		pub fn fold_map<M>(
			self,
			f: impl FnOnce(A) -> M,
		) -> M {
			f(self.0)
		}
	}

	#[document_type_parameters("The lifetime of the values.", "The type of the wrapped value.")]
	#[document_parameters("The identity instance.")]
	impl<'a, A: 'a> Identity<A> {
		/// Traverses the identity with an applicative function.
		///
		/// See [`Traversable::traverse`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters(
			"The type of the elements in the resulting identity.",
			"The applicative context."
		)]
		///
		#[document_parameters(
			"The function to apply, returning a value in an applicative context."
		)]
		///
		#[document_returns("The identity wrapped in the applicative context.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = x.traverse::<_, OptionBrand>(|a| Some(a * 2));
		/// assert_eq!(y, Some(Identity(10)));
		/// ```
		pub fn traverse<B: 'a + Clone, F: Applicative>(
			self,
			f: impl Fn(A) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) + 'a,
		) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Identity<B>>)
		where
			Identity<B>: Clone, {
			F::map(|b| Identity(b), f(self.0))
		}

		/// Sequences an identity containing an applicative value.
		///
		/// See [`Traversable::sequence`] for the type class version.
		#[document_signature]
		///
		#[document_type_parameters(
			"The inner type wrapped in the applicative context.",
			"The applicative context."
		)]
		///
		#[document_returns("The identity wrapped in the applicative context.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(Some(5));
		/// let y: Option<Identity<i32>> = x.sequence::<i32, OptionBrand>();
		/// assert_eq!(y, Some(Identity(5)));
		/// ```
		pub fn sequence<InnerA: 'a + Clone, F: Applicative>(
			self
		) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Identity<InnerA>>)
		where
			A: Into<Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, InnerA>)>,
			Identity<InnerA>: Clone, {
			F::map(|a| Identity(a), self.0.into())
		}
	}

	impl Functor for IdentityBrand {
		/// Maps a function over the value in the identity.
		///
		/// This method applies a function to the value inside the identity, producing a new identity with the transformed value.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the value.",
			"The type of the value inside the identity.",
			"The type of the result of applying the function."
		)]
		///
		#[document_parameters("The function to apply.", "The identity to map over.")]
		///
		#[document_returns("A new identity containing the result of applying the function.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = map::<IdentityBrand, _, _>(|i| i * 2, x);
		/// assert_eq!(y, Identity(10));
		/// ```
		fn map<'a, A: 'a, B: 'a>(
			func: impl Fn(A) -> B + 'a,
			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>) {
			fa.map(func)
		}
	}

	impl Lift for IdentityBrand {
		/// Lifts a binary function into the identity context.
		///
		/// This method lifts a binary function to operate on values within the identity context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The type of the first identity's value.",
			"The type of the second identity's value.",
			"The return type of the function."
		)]
		///
		#[document_parameters(
			"The binary function to apply.",
			"The first identity.",
			"The second identity."
		)]
		///
		#[document_returns("A new identity containing the result of applying the function.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(1);
		/// let y = Identity(2);
		/// let z = lift2::<IdentityBrand, _, _, _>(|a, b| a + b, x, y);
		/// assert_eq!(z, Identity(3));
		/// ```
		fn lift2<'a, A, B, C>(
			func: impl Fn(A, B) -> C + 'a,
			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
			A: 'a,
			B: 'a,
			C: 'a, {
			fa.lift2(fb, func)
		}
	}

	impl Pointed for IdentityBrand {
		/// Wraps a value in an identity.
		///
		/// This method wraps a value in an identity context.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the value.", "The type of the value to wrap.")]
		///
		#[document_parameters("The value to wrap.")]
		///
		#[document_returns("An identity containing the value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = pure::<IdentityBrand, _>(5);
		/// assert_eq!(x, Identity(5));
		/// ```
		fn pure<'a, A: 'a>(a: A) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
			Identity(a) // Identity constructor is already equivalent to pure
		}
	}

	impl ApplyFirst for IdentityBrand {}
	impl ApplySecond for IdentityBrand {}

	impl Semiapplicative for IdentityBrand {
		/// Applies a wrapped function to a wrapped value.
		///
		/// This method applies a function wrapped in an identity to a value wrapped in an identity.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function wrapper.",
			"The type of the input value.",
			"The type of the output value."
		)]
		///
		#[document_parameters(
			"The identity containing the function.",
			"The identity containing the value."
		)]
		///
		#[document_returns("A new identity containing the result of applying the function.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let f = Identity(cloneable_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2));
		/// let x = Identity(5);
		/// let y = apply::<RcFnBrand, IdentityBrand, _, _>(f, x);
		/// assert_eq!(y, Identity(10));
		/// ```
		fn apply<'a, FnBrand: 'a + CloneableFn, A: 'a + Clone, B: 'a>(
			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>) {
			fa.apply(ff.map(|f| move |a| f(a)))
		}
	}

	impl Semimonad for IdentityBrand {
		/// Chains identity computations.
		///
		/// This method chains two identity computations, where the second computation depends on the result of the first.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The type of the result of the first computation.",
			"The type of the result of the second computation."
		)]
		///
		#[document_parameters(
			"The first identity.",
			"The function to apply to the value inside the identity."
		)]
		///
		#[document_returns("The result of applying `f` to the value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = bind::<IdentityBrand, _, _>(x, |i| Identity(i * 2));
		/// assert_eq!(y, Identity(10));
		/// ```
		fn bind<'a, A: 'a, B: 'a>(
			ma: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
			func: impl Fn(A) -> Apply!(<Self 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>) {
			ma.bind(func)
		}
	}

	impl Foldable for IdentityBrand {
		/// Folds the identity from the right.
		///
		/// This method performs a right-associative fold of the identity. Since `Identity` contains only one element, this is equivalent to applying the function to the element and the initial value.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the structure.",
			"The type of the accumulator."
		)]
		///
		#[document_parameters(
			"The function to apply to each element and the accumulator.",
			"The initial value of the accumulator.",
			"The identity to fold."
		)]
		///
		#[document_returns("The final accumulator value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = fold_right::<RcFnBrand, IdentityBrand, _, _>(|a, b| a + b, 10, x);
		/// assert_eq!(y, 15);
		/// ```
		fn fold_right<'a, FnBrand, A: 'a, B: 'a>(
			func: impl Fn(A, B) -> B + 'a,
			initial: B,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> B
		where
			FnBrand: CloneableFn + 'a, {
			fa.fold_right(func, initial)
		}

		/// Folds the identity from the left.
		///
		/// This method performs a left-associative fold of the identity. Since `Identity` contains only one element, this is equivalent to applying the function to the initial value and the element.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the structure.",
			"The type of the accumulator."
		)]
		///
		#[document_parameters(
			"The function to apply to the accumulator and each element.",
			"The initial value of the accumulator.",
			"The structure to fold."
		)]
		///
		#[document_returns("The final accumulator value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = fold_left::<RcFnBrand, IdentityBrand, _, _>(|b, a| b + a, 10, x);
		/// assert_eq!(y, 15);
		/// ```
		fn fold_left<'a, FnBrand, A: 'a, B: 'a>(
			func: impl Fn(B, A) -> B + 'a,
			initial: B,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> B
		where
			FnBrand: CloneableFn + 'a, {
			fa.fold_left(func, initial)
		}

		/// Maps the value to a monoid and returns it.
		///
		/// This method maps the element of the identity to a monoid.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the structure.",
			"The type of the monoid."
		)]
		///
		#[document_parameters("The mapping function.", "The identity to fold.")]
		///
		#[document_returns("The monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = fold_map::<RcFnBrand, IdentityBrand, _, _>(|a: i32| a.to_string(), x);
		/// assert_eq!(y, "5".to_string());
		/// ```
		fn fold_map<'a, FnBrand, A: 'a, M>(
			func: impl Fn(A) -> M + 'a,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> M
		where
			M: Monoid + 'a,
			FnBrand: CloneableFn + 'a, {
			fa.fold_map(func)
		}
	}

	impl Traversable for IdentityBrand {
		/// Traverses the identity with an applicative function.
		///
		/// This method maps the element of the identity to a computation, evaluates it, and wraps the result in the applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The type of the elements in the traversable structure.",
			"The type of the elements in the resulting traversable structure.",
			"The applicative context."
		)]
		///
		#[document_parameters(
			"The function to apply to each element, returning a value in an applicative context.",
			"The identity to traverse."
		)]
		///
		#[document_returns("The identity wrapped in the applicative context.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(5);
		/// let y = traverse::<IdentityBrand, _, _, OptionBrand>(|a| Some(a * 2), x);
		/// assert_eq!(y, Some(Identity(10)));
		/// ```
		fn traverse<'a, A: 'a + Clone, B: 'a + Clone, F: Applicative>(
			func: impl Fn(A) -> Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) + 'a,
			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
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>): Clone, {
			ta.traverse::<B, F>(func)
		}

		/// Sequences an identity of applicative.
		///
		/// This method evaluates the computation inside the identity and wraps the result in the applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The type of the elements in the traversable structure.",
			"The applicative context."
		)]
		///
		#[document_parameters("The identity containing the applicative value.")]
		///
		#[document_returns("The result of the traversal.")]
		///
		/// # Returns
		///
		/// The identity wrapped in the applicative context.
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(Some(5));
		/// let y = sequence::<IdentityBrand, _, OptionBrand>(x);
		/// assert_eq!(y, Some(Identity(5)));
		/// ```
		fn sequence<'a, A: 'a + Clone, F: Applicative>(
			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, {
			ta.traverse::<A, F>(|a| a)
		}
	}

	impl ParFoldable for IdentityBrand {
		/// Maps the value to a monoid and returns it in parallel.
		///
		/// This method maps the element of the identity to a monoid. Since `Identity` contains only one element, no actual parallelism occurs, but the interface is satisfied.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function wrapper.",
			"The element type.",
			"The monoid type."
		)]
		///
		#[document_parameters("The mapping function.", "The identity to fold.")]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(1);
		/// let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|x: i32| x.to_string());
		/// let y = par_fold_map::<ArcFnBrand, IdentityBrand, _, _>(f, x);
		/// assert_eq!(y, "1".to_string());
		/// ```
		fn par_fold_map<'a, FnBrand, A, M>(
			func: <FnBrand as SendCloneableFn>::SendOf<'a, A, M>,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> M
		where
			FnBrand: 'a + SendCloneableFn,
			A: 'a + Clone + Send + Sync,
			M: Monoid + Send + Sync + 'a, {
			func(fa.0)
		}

		/// Folds the identity from the right in parallel.
		///
		/// This method performs a right-associative fold of the identity. Since `Identity` contains only one element, no actual parallelism occurs.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function wrapper.",
			"The element type.",
			"The accumulator type."
		)]
		///
		#[document_parameters(
			"The thread-safe function to apply to each element and the accumulator.",
			"The initial value of the accumulator.",
			"The identity to fold."
		)]
		///
		#[document_returns("The final accumulator value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// 	types::*,
		/// };
		///
		/// let x = Identity(1);
		/// let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|(a, b): (i32, i32)| a + b);
		/// let y = par_fold_right::<ArcFnBrand, IdentityBrand, _, _>(f, 10, x);
		/// assert_eq!(y, 11);
		/// ```
		fn par_fold_right<'a, FnBrand, A, B>(
			func: <FnBrand as SendCloneableFn>::SendOf<'a, (A, B), B>,
			initial: B,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> B
		where
			FnBrand: 'a + SendCloneableFn,
			A: 'a + Clone + Send + Sync,
			B: Send + Sync + 'a, {
			func((fa.0, initial))
		}
	}
}
pub use inner::*;

#[cfg(test)]
mod tests {
	use {
		super::inner::Identity,
		crate::{
			brands::{
				IdentityBrand,
				OptionBrand,
				RcFnBrand,
			},
			classes::{
				cloneable_fn::CloneableFn,
				functor::map,
				pointed::pure,
				semiapplicative::apply,
				semimonad::bind,
			},
			functions::{
				compose,
				identity,
			},
		},
		quickcheck_macros::quickcheck,
	};

	// Functor Laws

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

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

	// Applicative Laws

	/// Tests the identity law for Applicative.
	#[quickcheck]
	fn applicative_identity(v: i32) -> bool {
		let v = Identity(v);
		apply::<RcFnBrand, IdentityBrand, _, _>(
			pure::<IdentityBrand, _>(<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, IdentityBrand, _, _>(
			pure::<IdentityBrand, _>(<RcFnBrand as CloneableFn>::new(f)),
			pure::<IdentityBrand, _>(x),
		) == pure::<IdentityBrand, _>(f(x))
	}

	/// Tests the composition law for Applicative.
	#[quickcheck]
	fn applicative_composition(
		w: i32,
		u_val: i32,
		v_val: i32,
	) -> bool {
		let w = Identity(w);
		let v_fn = move |x: i32| x.wrapping_mul(v_val);
		let u_fn = move |x: i32| x.wrapping_add(u_val);

		let v = pure::<IdentityBrand, _>(<RcFnBrand as CloneableFn>::new(v_fn));
		let u = pure::<IdentityBrand, _>(<RcFnBrand as CloneableFn>::new(u_fn));

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

		// LHS: pure(compose) <*> u <*> v <*> w
		// equivalent to (u . v) <*> w
		let composed = move |x| u_fn(v_fn(x));
		let uv = pure::<IdentityBrand, _>(<RcFnBrand as CloneableFn>::new(composed));

		let lhs = apply::<RcFnBrand, IdentityBrand, _, _>(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::<IdentityBrand, _>(<RcFnBrand as CloneableFn>::new(f));

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

		let rhs_fn =
			<RcFnBrand as CloneableFn>::new(move |f: std::rc::Rc<dyn Fn(i32) -> i32>| f(y));
		let rhs = apply::<RcFnBrand, IdentityBrand, _, _>(pure::<IdentityBrand, _>(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| Identity(x.wrapping_mul(2));
		bind::<IdentityBrand, _, _>(pure::<IdentityBrand, _>(a), f) == f(a)
	}

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

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

	// Edge Cases

	/// Tests the `map` function.
	#[test]
	fn map_test() {
		assert_eq!(map::<IdentityBrand, _, _>(|x: i32| x + 1, Identity(1)), Identity(2));
	}

	/// Tests the `bind` function.
	#[test]
	fn bind_test() {
		assert_eq!(bind::<IdentityBrand, _, _>(Identity(1), |x| Identity(x + 1)), Identity(2));
	}

	/// Tests the `fold_right` function.
	#[test]
	fn fold_right_test() {
		assert_eq!(
			crate::classes::foldable::fold_right::<RcFnBrand, IdentityBrand, _, _>(
				|x: i32, acc| x + acc,
				0,
				Identity(1)
			),
			1
		);
	}

	/// Tests the `fold_left` function.
	#[test]
	fn fold_left_test() {
		assert_eq!(
			crate::classes::foldable::fold_left::<RcFnBrand, IdentityBrand, _, _>(
				|acc, x: i32| acc + x,
				0,
				Identity(1)
			),
			1
		);
	}

	/// Tests the `traverse` function.
	#[test]
	fn traverse_test() {
		assert_eq!(
			crate::classes::traversable::traverse::<IdentityBrand, _, _, OptionBrand>(
				|x: i32| Some(x + 1),
				Identity(1)
			),
			Some(Identity(2))
		);
	}

	// ParFoldable Tests

	/// Tests `par_fold_map`.
	#[test]
	fn par_fold_map_test() {
		use crate::{
			brands::*,
			functions::*,
		};

		let x = Identity(1);
		let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|x: i32| x.to_string());
		assert_eq!(par_fold_map::<ArcFnBrand, IdentityBrand, _, _>(f, x), "1".to_string());
	}

	/// Tests `par_fold_right`.
	#[test]
	fn par_fold_right_test() {
		use crate::{
			brands::*,
			functions::*,
		};

		let x = Identity(1);
		let f = send_cloneable_fn_new::<ArcFnBrand, _, _>(|(a, b): (i32, i32)| a + b);
		assert_eq!(par_fold_right::<ArcFnBrand, IdentityBrand, _, _>(f, 10, x), 11);
	}
}