fp-library 0.14.0

//! Functional programming trait implementations for the standard library [`Vec`] type.
//!
//! Extends `Vec` with [`Functor`](crate::classes::Functor), [`Monad`](crate::classes::semimonad::Semimonad), [`Foldable`](crate::classes::Foldable), [`Traversable`](crate::classes::Traversable), [`Extend`](crate::classes::Extend), [`Filterable`](crate::classes::Filterable), [`Witherable`](crate::classes::Witherable), and parallel folding instances.

#[fp_macros::document_module]
mod inner {
	use {
		crate::{
			Apply,
			brands::{
				OptionBrand,
				VecBrand,
			},
			classes::{
				Alt,
				Applicative,
				ApplyFirst,
				ApplySecond,
				CloneableFn,
				Compactable,
				Extend,
				Filterable,
				Foldable,
				Functor,
				Lift,
				MonadRec,
				Monoid,
				ParCompactable,
				ParFilterable,
				ParFoldable,
				ParFunctor,
				Plus,
				Pointed,
				Semiapplicative,
				Semigroup,
				Semimonad,
				Traversable,
				Witherable,
				foldable_with_index::FoldableWithIndex,
				functor_with_index::FunctorWithIndex,
				par_foldable_with_index::ParFoldableWithIndex,
				par_functor_with_index::ParFunctorWithIndex,
				traversable_with_index::TraversableWithIndex,
				with_index::WithIndex,
			},
			impl_kind,
			kinds::*,
		},
		core::ops::ControlFlow,
		fp_macros::*,
	};

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

	impl VecBrand {
		/// Constructs a new vector by prepending a value to an existing vector.
		///
		/// This method creates a new vector with the given head element followed by the elements of the tail vector.
		#[document_signature]
		///
		#[document_type_parameters("The type of the elements in the vector.")]
		///
		#[document_parameters(
			"A value to prepend to the vector.",
			"A vector to prepend the value to."
		)]
		///
		#[document_returns(
			"A new vector consisting of the `head` element prepended to the `tail` vector."
		)]
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let head = 1;
		/// let tail = vec![2, 3];
		/// let new_vec = VecBrand::construct(head, tail);
		/// assert_eq!(new_vec, vec![1, 2, 3]);
		///
		/// let empty_tail = vec![];
		/// let single_element = VecBrand::construct(42, empty_tail);
		/// assert_eq!(single_element, vec![42]);
		/// ```
		pub fn construct<A>(
			head: A,
			tail: Vec<A>,
		) -> Vec<A>
		where
			A: Clone, {
			[vec![head], tail].concat()
		}

		/// Deconstructs a slice into its head element and tail vector.
		///
		/// This method splits a slice into its first element and the rest of the elements as a new vector.
		#[document_signature]
		///
		#[document_type_parameters("The type of the elements in the vector.")]
		///
		#[document_parameters("The vector slice to deconstruct.")]
		///
		#[document_returns(
			"An [`Option`] containing a tuple of the head element and the remaining tail vector, or [`None`] if the slice is empty."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let vec = vec![1, 2, 3];
		/// let deconstructed = VecBrand::deconstruct(&vec);
		/// assert_eq!(deconstructed, Some((1, vec![2, 3])));
		///
		/// let empty: Vec<i32> = vec![];
		/// assert_eq!(VecBrand::deconstruct(&empty), None);
		/// ```
		pub fn deconstruct<A>(slice: &[A]) -> Option<(A, Vec<A>)>
		where
			A: Clone, {
			match slice {
				[] => None,
				[head, tail @ ..] => Some((head.clone(), tail.to_vec())),
			}
		}
	}

	impl Functor for VecBrand {
		/// Maps a function over the vector.
		///
		/// This method applies a function to each element of the vector, producing a new vector with the transformed values.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the vector.",
			"The type of the elements in the resulting vector."
		)]
		///
		#[document_parameters("The function to apply to each element.", "The vector to map over.")]
		///
		#[document_returns("A new vector containing the results of applying the function.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(map::<VecBrand, _, _>(|x: i32| x * 2, vec![1, 2, 3]), vec![2, 4, 6]);
		/// ```
		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.into_iter().map(func).collect()
		}
	}

	impl Lift for VecBrand {
		/// Lifts a binary function into the vector context (Cartesian product).
		///
		/// This method applies a binary function to all pairs of elements from two vectors, producing a new vector containing the results (Cartesian product).
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the first vector.",
			"The type of the elements in the second vector.",
			"The type of the elements in the resulting vector."
		)]
		///
		#[document_parameters(
			"The binary function to apply.",
			"The first vector.",
			"The second vector."
		)]
		///
		#[document_returns(
			"A new vector containing the results of applying the function to all pairs of elements."
		)]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(
		/// 	lift2::<VecBrand, _, _, _>(|x, y| x + y, vec![1, 2], vec![10, 20]),
		/// 	vec![11, 21, 12, 22]
		/// );
		/// ```
		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: Clone + 'a,
			B: Clone + 'a,
			C: 'a, {
			fa.iter().flat_map(|a| fb.iter().map(|b| func(a.clone(), b.clone()))).collect()
		}
	}

	impl Pointed for VecBrand {
		/// Wraps a value in a vector.
		///
		/// This method creates a new vector containing the single given value.
		#[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("A vector containing the single value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(pure::<VecBrand, _>(5), vec![5]);
		/// ```
		fn pure<'a, A: 'a>(a: A) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
			vec![a]
		}
	}

	impl ApplyFirst for VecBrand {}
	impl ApplySecond for VecBrand {}

	impl Semiapplicative for VecBrand {
		/// Applies wrapped functions to wrapped values (Cartesian product).
		///
		/// This method applies each function in the first vector to each value in the second vector, producing a new vector containing all the results.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The brand of the cloneable function wrapper.",
			"The type of the input values.",
			"The type of the output values."
		)]
		///
		#[document_parameters(
			"The vector containing the functions.",
			"The vector containing the values."
		)]
		///
		#[document_returns(
			"A new vector containing the results of applying each function to each value."
		)]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	classes::*,
		/// 	functions::*,
		/// };
		///
		/// let funcs = vec![
		/// 	cloneable_fn_new::<RcFnBrand, _, _>(|x: i32| x + 1),
		/// 	cloneable_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2),
		/// ];
		/// assert_eq!(apply::<RcFnBrand, VecBrand, _, _>(funcs, vec![1, 2]), vec![2, 3, 2, 4]);
		/// ```
		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>) {
			ff.iter().flat_map(|f| fa.iter().map(move |a| f(a.clone()))).collect()
		}
	}

	impl Semimonad for VecBrand {
		/// Chains vector computations (`flat_map`).
		///
		/// This method applies a function that returns a vector to each element of the input vector, and then flattens the result.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the input vector.",
			"The type of the elements in the output vector."
		)]
		///
		#[document_parameters(
			"The first vector.",
			"The function to apply to each element, returning a vector."
		)]
		///
		#[document_returns("A new vector containing the flattened results.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(bind::<VecBrand, _, _>(vec![1, 2], |x| vec![x, x * 2]), vec![1, 2, 2, 4]);
		/// ```
		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.into_iter().flat_map(func).collect()
		}
	}

	impl Alt for VecBrand {
		/// Concatenates two vectors.
		///
		/// This is the same as [`Semigroup::append`] for `Vec`, providing an
		/// associative choice operation for the `Vec` type constructor.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The type of the elements.")]
		///
		#[document_parameters("The first vector.", "The second vector.")]
		///
		#[document_returns("The concatenated vector.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	classes::*,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2];
		/// let y = vec![3, 4];
		/// assert_eq!(alt::<VecBrand, _>(x, y), vec![1, 2, 3, 4]);
		/// ```
		fn alt<'a, A: 'a>(
			fa1: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
			fa2: 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>) {
			let mut result = fa1;
			result.extend(fa2);
			result
		}
	}

	impl Plus for VecBrand {
		/// Returns an empty vector, the identity element for [`alt`](Alt::alt).
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The type of the elements.")]
		///
		#[document_returns("An empty vector.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let x: Vec<i32> = plus_empty::<VecBrand, i32>();
		/// assert_eq!(x, vec![]);
		/// ```
		fn empty<'a, A: 'a>() -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
			Vec::new()
		}
	}

	impl Foldable for VecBrand {
		/// Folds the vector from the right.
		///
		/// This method performs a right-associative fold of the vector.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the vector.",
			"The type of the accumulator."
		)]
		///
		#[document_parameters("The folding function.", "The initial value.", "The vector to fold.")]
		///
		#[document_returns("The final accumulator value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(fold_right::<RcFnBrand, VecBrand, _, _>(|x: i32, acc| x + acc, 0, vec![1, 2, 3]), 6);
		/// ```
		fn fold_right<'a, FnBrand, A: 'a + Clone, 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.into_iter().rev().fold(initial, |acc, x| func(x, acc))
		}

		/// Folds the vector from the left.
		///
		/// This method performs a left-associative fold of the vector.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the vector.",
			"The type of the accumulator."
		)]
		///
		#[document_parameters(
			"The function to apply to the accumulator and each element.",
			"The initial value of the accumulator.",
			"The vector to fold."
		)]
		///
		#[document_returns("The final accumulator value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(fold_left::<RcFnBrand, VecBrand, _, _>(|acc, x: i32| acc + x, 0, vec![1, 2, 3]), 6);
		/// ```
		fn fold_left<'a, FnBrand, A: 'a + Clone, 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.into_iter().fold(initial, func)
		}

		/// Maps the values to a monoid and combines them.
		///
		/// This method maps each element of the vector to a monoid and then combines the results using the monoid's `append` operation.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The brand of the cloneable function to use.",
			"The type of the elements in the vector.",
			"The type of the monoid."
		)]
		///
		#[document_parameters("The mapping function.", "The vector to fold.")]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(
		/// 	fold_map::<RcFnBrand, VecBrand, _, _>(|x: i32| x.to_string(), vec![1, 2, 3]),
		/// 	"123".to_string()
		/// );
		/// ```
		fn fold_map<'a, FnBrand, A: 'a + Clone, 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.into_iter().map(func).fold(M::empty(), |acc, x| M::append(acc, x))
		}
	}

	impl Traversable for VecBrand {
		/// Traverses the vector with an applicative function.
		///
		/// This method maps each element of the vector to a computation, evaluates them, and combines the results into an applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"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 vector to traverse."
		)]
		///
		#[document_returns("The vector wrapped in the applicative context.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		OptionBrand,
		/// 		VecBrand,
		/// 	},
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(
		/// 	traverse::<VecBrand, _, _, OptionBrand>(|x| Some(x * 2), vec![1, 2, 3]),
		/// 	Some(vec![2, 4, 6])
		/// );
		/// ```
		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,
			Apply!(<F as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>): Clone, {
			let len = ta.len();
			ta.into_iter().fold(F::pure(Vec::with_capacity(len)), |acc, x| {
				F::lift2(
					|mut v, b| {
						v.push(b);
						v
					},
					acc,
					func(x),
				)
			})
		}

		/// Sequences a vector of applicative.
		///
		/// This method evaluates the computations inside the vector and accumulates the results into an applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the traversable structure.",
			"The applicative context."
		)]
		///
		#[document_parameters("The vector containing the applicative values.")]
		///
		#[document_returns("The vector wrapped in the applicative context.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		OptionBrand,
		/// 		VecBrand,
		/// 	},
		/// 	functions::*,
		/// };
		///
		/// assert_eq!(sequence::<VecBrand, _, OptionBrand>(vec![Some(1), Some(2)]), Some(vec![1, 2]));
		/// ```
		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, {
			let len = ta.len();
			ta.into_iter().fold(F::pure(Vec::with_capacity(len)), |acc, x| {
				F::lift2(
					|mut v, a| {
						v.push(a);
						v
					},
					acc,
					x,
				)
			})
		}
	}

	impl WithIndex for VecBrand {
		type Index = usize;
	}

	impl FunctorWithIndex for VecBrand {
		/// Maps a function over the vector, providing the index of each element.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the vector.",
			"The type of the elements in the resulting vector."
		)]
		#[document_parameters(
			"The function to apply to each element and its index.",
			"The vector to map over."
		)]
		#[document_returns("A new vector containing the results of applying the function.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		/// let v = vec![10, 20, 30];
		/// // Use `map_with_index` via the method on the trait, or a helper function if one existed.
		/// // Since there's no helper function in `functions.rs` yet, we use explicit syntax or call it via trait.
		/// use fp_library::classes::functor_with_index::FunctorWithIndex;
		/// let mapped = <VecBrand as FunctorWithIndex>::map_with_index(|i, x| x + i as i32, v);
		/// assert_eq!(mapped, vec![10, 21, 32]);
		/// ```
		fn map_with_index<'a, A: 'a, B: 'a>(
			f: impl Fn(usize, A) -> B + 'a,
			fa: Vec<A>,
		) -> Vec<B> {
			fa.into_iter().enumerate().map(|(i, a)| f(i, a)).collect()
		}
	}

	impl FoldableWithIndex for VecBrand {
		/// Folds the vector using a monoid, providing the index of each element.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the vector.",
			"The monoid type."
		)]
		#[document_parameters(
			"The function to apply to each element and its index.",
			"The vector to fold."
		)]
		#[document_returns("The combined monoid value.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::foldable_with_index::FoldableWithIndex,
		/// 	functions::*,
		/// };
		/// let v = vec![10, 20, 30];
		/// let s = <VecBrand as FoldableWithIndex>::fold_map_with_index(|i, x| format!("{}:{}", i, x), v);
		/// assert_eq!(s, "0:101:202:30");
		/// ```
		fn fold_map_with_index<'a, A: 'a + Clone, R: Monoid>(
			f: impl Fn(usize, A) -> R + 'a,
			fa: Vec<A>,
		) -> R {
			fa.into_iter()
				.enumerate()
				.map(|(i, a)| f(i, a))
				.fold(R::empty(), |acc, x| R::append(acc, x))
		}
	}

	impl TraversableWithIndex for VecBrand {
		/// Traverses the vector with an applicative function, providing the index of each element.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the elements in the vector.",
			"The type of the elements in the resulting vector.",
			"The applicative context."
		)]
		#[document_parameters(
			"The function to apply to each element and its index, returning a value in an applicative context.",
			"The vector to traverse."
		)]
		#[document_returns("The vector wrapped in the applicative context.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		OptionBrand,
		/// 		VecBrand,
		/// 	},
		/// 	classes::traversable_with_index::TraversableWithIndex,
		/// 	functions::*,
		/// };
		/// let v = vec![10, 20, 30];
		/// let t = <VecBrand as TraversableWithIndex>::traverse_with_index::<i32, i32, OptionBrand>(
		/// 	|i, x| Some(x + i as i32),
		/// 	v,
		/// );
		/// assert_eq!(t, Some(vec![10, 21, 32]));
		/// ```
		fn traverse_with_index<'a, A: 'a, B: 'a + Clone, M: Applicative>(
			f: impl Fn(usize, A) -> M::Of<'a, B> + 'a,
			ta: Vec<A>,
		) -> M::Of<'a, Vec<B>> {
			let len = ta.len();
			ta.into_iter().enumerate().fold(M::pure(Vec::with_capacity(len)), |acc, (i, x)| {
				M::lift2(
					|mut v, b| {
						v.push(b);
						v
					},
					acc,
					f(i, x),
				)
			})
		}
	}

	#[document_type_parameters("The type of the elements in the vector.")]
	impl<A: Clone> Semigroup for Vec<A> {
		/// Appends one vector to another.
		///
		/// This method concatenates two vectors.
		#[document_signature]
		///
		#[document_parameters("The first vector.", "The second vector.")]
		///
		#[document_returns("The concatenated vector.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::functions::*;
		///
		/// assert_eq!(append(vec![1, 2], vec![3, 4]), vec![1, 2, 3, 4]);
		/// ```
		fn append(
			a: Self,
			b: Self,
		) -> Self {
			[a, b].concat()
		}
	}

	#[document_type_parameters("The type of the elements in the vector.")]
	impl<A: Clone> Monoid for Vec<A> {
		/// Returns an empty vector.
		///
		/// This method returns a new, empty vector.
		#[document_signature]
		///
		#[document_returns("An empty vector.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::functions::*;
		///
		/// assert_eq!(empty::<Vec<i32>>(), vec![]);
		/// ```
		fn empty() -> Self {
			Vec::new()
		}
	}

	impl VecBrand {
		/// Maps a function over the vector in parallel.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential mapping.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply to each element. Must be `Send + Sync`.",
			"The vector to map over."
		)]
		///
		#[document_returns("A new vector containing the mapped elements.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_map(|x: i32| x * 2, vec![1, 2, 3]);
		/// assert_eq!(result, vec![2, 4, 6]);
		/// ```
		pub fn par_map<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(A) -> B + Send + Sync + 'a,
			fa: Vec<A>,
		) -> Vec<B> {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().map(f).collect()
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().map(f).collect()
		}

		/// Compacts a vector of options in parallel, discarding `None` values.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential compaction.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The element type.")]
		///
		#[document_parameters("The vector of options.")]
		///
		#[document_returns("A new vector containing the unwrapped `Some` values.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_compact(vec![Some(1), None, Some(3)]);
		/// assert_eq!(result, vec![1, 3]);
		/// ```
		pub fn par_compact<'a, A: 'a + Send>(fa: Vec<Option<A>>) -> Vec<A> {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().flatten().collect()
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().flatten().collect()
		}

		/// Separates a vector of results into `(errors, oks)` in parallel.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential separation.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The error type.",
			"The success type."
		)]
		///
		#[document_parameters("The vector of results.")]
		///
		#[document_returns(
			"A pair `(errs, oks)` where `errs` contains the `Err` values and `oks` the `Ok` values."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let v: Vec<Result<i32, &str>> = vec![Ok(1), Err("a"), Ok(3)];
		/// let (errs, oks): (Vec<&str>, Vec<i32>) = VecBrand::par_separate(v);
		/// assert_eq!(errs, vec!["a"]);
		/// assert_eq!(oks, vec![1, 3]);
		/// ```
		pub fn par_separate<'a, E: 'a + Send, O: 'a + Send>(
			fa: Vec<Result<O, E>>
		) -> (Vec<E>, Vec<O>) {
			#[cfg(feature = "rayon")]
			{
				use rayon::{
					iter::Either,
					prelude::*,
				};
				fa.into_par_iter().partition_map(|r| match r {
					Ok(o) => Either::Right(o),
					Err(e) => Either::Left(e),
				})
			}
			#[cfg(not(feature = "rayon"))]
			{
				let mut errs = Vec::new();
				let mut oks = Vec::new();
				for result in fa {
					match result {
						Ok(o) => oks.push(o),
						Err(e) => errs.push(e),
					}
				}
				(errs, oks)
			}
		}

		/// Maps and filters a vector in parallel, discarding elements where `f` returns `None`.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential filter-mapping.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply. Must be `Send + Sync`.",
			"The vector to filter and map."
		)]
		///
		#[document_returns("A new vector containing the `Some` results of applying `f`.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_filter_map(
		/// 	|x: i32| if x % 2 == 0 { Some(x * 10) } else { None },
		/// 	vec![1, 2, 3, 4, 5],
		/// );
		/// assert_eq!(result, vec![20, 40]);
		/// ```
		pub fn par_filter_map<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(A) -> Option<B> + Send + Sync + 'a,
			fa: Vec<A>,
		) -> Vec<B> {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().filter_map(f).collect()
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().filter_map(f).collect()
		}

		/// Filters a vector in parallel, retaining only elements satisfying `f`.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential filtering.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The element type.")]
		///
		#[document_parameters("The predicate. Must be `Send + Sync`.", "The vector to filter.")]
		///
		#[document_returns("A new vector containing only the elements satisfying `f`.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_filter(|x: &i32| x % 2 == 0, vec![1, 2, 3, 4, 5]);
		/// assert_eq!(result, vec![2, 4]);
		/// ```
		pub fn par_filter<'a, A: 'a + Send>(
			f: impl Fn(&A) -> bool + Send + Sync + 'a,
			fa: Vec<A>,
		) -> Vec<A> {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().filter(|a| f(a)).collect()
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().filter(|a| f(a)).collect()
		}

		/// Maps each element to a [`Monoid`] value and combines them in parallel.
		///
		/// When the `rayon` feature is enabled, mapping and reduction happen across multiple threads.
		/// Otherwise falls back to sequential fold-map.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The element type.",
			"The monoid type."
		)]
		///
		#[document_parameters(
			"The function mapping each element to a monoid value. Must be `Send + Sync`.",
			"The vector to fold."
		)]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_fold_map(|x: i32| x.to_string(), vec![1, 2, 3]);
		/// assert_eq!(result, "123");
		/// ```
		pub fn par_fold_map<'a, A: 'a + Send, M: Monoid + Send + 'a>(
			f: impl Fn(A) -> M + Send + Sync + 'a,
			fa: Vec<A>,
		) -> M {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().map(f).reduce(M::empty, |acc, m| M::append(acc, m))
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().map(f).fold(M::empty(), |acc, m| M::append(acc, m))
		}

		/// Maps a function over the vector in parallel, providing each element's index.
		///
		/// When the `rayon` feature is enabled, elements are processed across multiple threads.
		/// Otherwise falls back to sequential indexed mapping.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply to each index and element. Must be `Send + Sync`.",
			"The vector to map over."
		)]
		///
		#[document_returns("A new vector containing the mapped elements.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result = VecBrand::par_map_with_index(|i, x: i32| x + i as i32, vec![10, 20, 30]);
		/// assert_eq!(result, vec![10, 21, 32]);
		/// ```
		pub fn par_map_with_index<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(usize, A) -> B + Send + Sync + 'a,
			fa: Vec<A>,
		) -> Vec<B> {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter().enumerate().map(|(i, a)| f(i, a)).collect()
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter().enumerate().map(|(i, a)| f(i, a)).collect()
		}

		/// Maps each element and its index to a [`Monoid`] value and combines them in parallel.
		///
		/// When the `rayon` feature is enabled, mapping and reduction happen across multiple threads.
		/// Otherwise falls back to sequential indexed fold-map.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The element type.",
			"The monoid type."
		)]
		///
		#[document_parameters(
			"The function mapping each index and element to a monoid value. Must be `Send + Sync`.",
			"The vector to fold."
		)]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::brands::VecBrand;
		///
		/// let result =
		/// 	VecBrand::par_fold_map_with_index(|i, x: i32| format!("{i}:{x}"), vec![10, 20, 30]);
		/// assert_eq!(result, "0:101:202:30");
		/// ```
		pub fn par_fold_map_with_index<'a, A: 'a + Send, M: Monoid + Send + 'a>(
			f: impl Fn(usize, A) -> M + Send + Sync + 'a,
			fa: Vec<A>,
		) -> M {
			#[cfg(feature = "rayon")]
			{
				use rayon::prelude::*;
				fa.into_par_iter()
					.enumerate()
					.map(|(i, a)| f(i, a))
					.reduce(M::empty, |acc, m| M::append(acc, m))
			}
			#[cfg(not(feature = "rayon"))]
			fa.into_iter()
				.enumerate()
				.map(|(i, a)| f(i, a))
				.fold(M::empty(), |acc, m| M::append(acc, m))
		}
	}

	impl ParFunctor for VecBrand {
		/// Maps a function over the vector in parallel.
		///
		/// Delegates to [`VecBrand::par_map`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply to each element. Must be `Send + Sync`.",
			"The vector to map over."
		)]
		///
		#[document_returns("A new vector containing the mapped elements.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_functor::ParFunctor,
		/// };
		///
		/// let result = VecBrand::par_map(|x: i32| x * 2, vec![1, 2, 3]);
		/// assert_eq!(result, vec![2, 4, 6]);
		/// ```
		fn par_map<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(A) -> B + Send + Sync + '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>) {
			VecBrand::par_map(f, fa)
		}
	}

	impl ParCompactable for VecBrand {
		/// Compacts a vector of options in parallel, discarding `None` values.
		///
		/// Delegates to [`VecBrand::par_compact`].
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The element type.")]
		///
		#[document_parameters("The vector of options.")]
		///
		#[document_returns("A new vector containing the unwrapped `Some` values.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_compactable::ParCompactable,
		/// };
		///
		/// let result = VecBrand::par_compact(vec![Some(1), None, Some(3)]);
		/// assert_eq!(result, vec![1, 3]);
		/// ```
		fn par_compact<'a, A: 'a + Send>(
			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>) {
			VecBrand::par_compact(fa)
		}

		/// Separates a vector of results into `(errors, oks)` in parallel.
		///
		/// Delegates to [`VecBrand::par_separate`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The error type.",
			"The success type."
		)]
		///
		#[document_parameters("The vector of results.")]
		///
		#[document_returns(
			"A pair `(errs, oks)` where `errs` contains the `Err` values and `oks` the `Ok` values."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_compactable::ParCompactable,
		/// };
		///
		/// let v: Vec<Result<i32, &str>> = vec![Ok(1), Err("a"), Ok(3)];
		/// let (errs, oks): (Vec<&str>, Vec<i32>) = VecBrand::par_separate(v);
		/// assert_eq!(errs, vec!["a"]);
		/// assert_eq!(oks, vec![1, 3]);
		/// ```
		fn par_separate<'a, E: 'a + Send, O: 'a + Send>(
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
		) -> (
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		) {
			VecBrand::par_separate(fa)
		}
	}

	impl ParFilterable for VecBrand {
		/// Maps and filters a vector in parallel, discarding elements where `f` returns `None`.
		///
		/// Single-pass implementation using rayon's `filter_map`. Delegates to
		/// [`VecBrand::par_filter_map`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply. Must be `Send + Sync`.",
			"The vector to filter and map."
		)]
		///
		#[document_returns("A new vector containing the `Some` results of applying `f`.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_filterable::ParFilterable,
		/// };
		///
		/// let result = VecBrand::par_filter_map(
		/// 	|x: i32| if x % 2 == 0 { Some(x * 10) } else { None },
		/// 	vec![1, 2, 3, 4, 5],
		/// );
		/// assert_eq!(result, vec![20, 40]);
		/// ```
		fn par_filter_map<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(A) -> Option<B> + Send + Sync + '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>) {
			VecBrand::par_filter_map(f, fa)
		}

		/// Filters a vector in parallel, retaining only elements satisfying `f`.
		///
		/// Single-pass implementation using rayon's `filter`. Delegates to
		/// [`VecBrand::par_filter`].
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The element type.")]
		///
		#[document_parameters("The predicate. Must be `Send + Sync`.", "The vector to filter.")]
		///
		#[document_returns("A new vector containing only the elements satisfying `f`.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_filterable::ParFilterable,
		/// };
		///
		/// let result = VecBrand::par_filter(|x: &i32| x % 2 == 0, vec![1, 2, 3, 4, 5]);
		/// assert_eq!(result, vec![2, 4]);
		/// ```
		fn par_filter<'a, A: 'a + Send>(
			f: impl Fn(&A) -> bool + Send + Sync + '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, A>) {
			VecBrand::par_filter(f, fa)
		}
	}

	impl ParFoldable for VecBrand {
		/// Maps each element to a [`Monoid`] value and combines them in parallel.
		///
		/// Delegates to [`VecBrand::par_fold_map`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The element type.",
			"The monoid type."
		)]
		///
		#[document_parameters(
			"The function mapping each element to a monoid value. Must be `Send + Sync`.",
			"The vector to fold."
		)]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_foldable::ParFoldable,
		/// };
		///
		/// let result = VecBrand::par_fold_map(|x: i32| x.to_string(), vec![1, 2, 3]);
		/// assert_eq!(result, "123");
		/// ```
		fn par_fold_map<'a, A: 'a + Send, M: Monoid + Send + 'a>(
			f: impl Fn(A) -> M + Send + Sync + 'a,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> M {
			VecBrand::par_fold_map(f, fa)
		}
	}

	impl ParFunctorWithIndex for VecBrand {
		/// Maps a function over the vector in parallel, providing each element's index.
		///
		/// Delegates to [`VecBrand::par_map_with_index`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The input element type.",
			"The output element type."
		)]
		///
		#[document_parameters(
			"The function to apply to each index and element. Must be `Send + Sync`.",
			"The vector to map over."
		)]
		///
		#[document_returns("A new vector containing the mapped elements.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_functor_with_index::ParFunctorWithIndex,
		/// };
		///
		/// let result = VecBrand::par_map_with_index(|i, x: i32| x + i as i32, vec![10, 20, 30]);
		/// assert_eq!(result, vec![10, 21, 32]);
		/// ```
		fn par_map_with_index<'a, A: 'a + Send, B: 'a + Send>(
			f: impl Fn(usize, A) -> B + Send + Sync + '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>)
		where
			usize: Send + Sync + Copy + 'a, {
			VecBrand::par_map_with_index(f, fa)
		}
	}

	impl ParFoldableWithIndex for VecBrand {
		/// Maps each element and its index to a [`Monoid`] value and combines them in parallel.
		///
		/// Delegates to [`VecBrand::par_fold_map_with_index`].
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The element type.",
			"The monoid type."
		)]
		///
		#[document_parameters(
			"The function mapping each index and element to a monoid value. Must be `Send + Sync`.",
			"The vector to fold."
		)]
		///
		#[document_returns("The combined monoid value.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	classes::par_foldable_with_index::ParFoldableWithIndex,
		/// };
		///
		/// let result =
		/// 	VecBrand::par_fold_map_with_index(|i, x: i32| format!("{i}:{x}"), vec![10, 20, 30]);
		/// assert_eq!(result, "0:101:202:30");
		/// ```
		fn par_fold_map_with_index<'a, A: 'a + Send, M: Monoid + Send + 'a>(
			f: impl Fn(usize, A) -> M + Send + Sync + 'a,
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) -> M
		where
			usize: Send + Sync + Copy + 'a, {
			VecBrand::par_fold_map_with_index(f, fa)
		}
	}

	impl Compactable for VecBrand {
		/// Compacts a vector of options.
		///
		/// This method flattens a vector of options, discarding `None` values.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The type of the elements.")]
		///
		#[document_parameters("The vector of options.")]
		///
		#[document_returns("The flattened vector.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![Some(1), None, Some(2)];
		/// let y = compact::<VecBrand, _>(x);
		/// assert_eq!(y, vec![1, 2]);
		/// ```
		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.into_iter().flatten().collect()
		}

		/// Separates a vector of results.
		///
		/// This method separates a vector of results into a pair of vectors.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the error value.",
			"The type of the success value."
		)]
		///
		#[document_parameters("The vector of results.")]
		///
		#[document_returns("A pair of vectors.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![Ok(1), Err("error"), Ok(2)];
		/// let (errs, oks) = separate::<VecBrand, _, _>(x);
		/// assert_eq!(oks, vec![1, 2]);
		/// assert_eq!(errs, vec!["error"]);
		/// ```
		fn separate<'a, E: 'a, O: 'a>(
			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
		) -> (
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		) {
			let mut oks = Vec::new();
			let mut errs = Vec::new();
			for result in fa {
				match result {
					Ok(o) => oks.push(o),
					Err(e) => errs.push(e),
				}
			}
			(errs, oks)
		}
	}

	impl Filterable for VecBrand {
		/// Partitions a vector based on a function that returns a result.
		///
		/// This method partitions a vector based on a function that returns a result.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the input value.",
			"The type of the error value.",
			"The type of the success value."
		)]
		///
		#[document_parameters("The function to apply.", "The vector to partition.")]
		///
		#[document_returns("A pair of vectors.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let (errs, oks) =
		/// 	partition_map::<VecBrand, _, _, _>(|a| if a % 2 == 0 { Ok(a) } else { Err(a) }, x);
		/// assert_eq!(oks, vec![2, 4]);
		/// assert_eq!(errs, vec![1, 3]);
		/// ```
		fn partition_map<'a, A: 'a, E: 'a, O: 'a>(
			func: impl Fn(A) -> Result<O, E> + '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, E>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		) {
			let mut oks = Vec::new();
			let mut errs = Vec::new();
			for a in fa {
				match func(a) {
					Ok(o) => oks.push(o),
					Err(e) => errs.push(e),
				}
			}
			(errs, oks)
		}

		/// Partitions a vector based on a predicate.
		///
		/// This method partitions a vector based on a predicate.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The type of the elements.")]
		///
		#[document_parameters("The predicate.", "The vector to partition.")]
		///
		#[document_returns("A pair of vectors.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let (not_satisfied, satisfied) = partition::<VecBrand, _>(|a| a % 2 == 0, x);
		/// assert_eq!(satisfied, vec![2, 4]);
		/// assert_eq!(not_satisfied, vec![1, 3]);
		/// ```
		fn partition<'a, A: 'a + Clone>(
			func: impl Fn(A) -> bool + '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, A>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
		) {
			let (satisfied, not_satisfied): (Vec<A>, Vec<A>) =
				fa.into_iter().partition(|a| func(a.clone()));
			(not_satisfied, satisfied)
		}

		/// Maps a function over a vector and filters out `None` results.
		///
		/// This method maps a function over a vector and filters out `None` results.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The type of the input value.",
			"The type of the result of applying the function."
		)]
		///
		#[document_parameters("The function to apply.", "The vector to filter and map.")]
		///
		#[document_returns("The filtered and mapped vector.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let y = filter_map::<VecBrand, _, _>(|a| if a % 2 == 0 { Some(a * 2) } else { None }, x);
		/// assert_eq!(y, vec![4, 8]);
		/// ```
		fn filter_map<'a, A: 'a, B: 'a>(
			func: impl Fn(A) -> Option<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.into_iter().filter_map(func).collect()
		}

		/// Filters a vector based on a predicate.
		///
		/// This method filters a vector based on a predicate.
		#[document_signature]
		///
		#[document_type_parameters("The lifetime of the elements.", "The type of the elements.")]
		///
		#[document_parameters("The predicate.", "The vector to filter.")]
		///
		#[document_returns("The filtered vector.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::VecBrand,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let y = filter::<VecBrand, _>(|a| a % 2 == 0, x);
		/// assert_eq!(y, vec![2, 4]);
		/// ```
		fn filter<'a, A: 'a + Clone>(
			func: impl Fn(A) -> bool + '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, A>) {
			fa.into_iter().filter(|a| func(a.clone())).collect()
		}
	}

	impl Witherable for VecBrand {
		/// Partitions a vector based on a function that returns a result in an applicative context.
		///
		/// This method partitions a vector based on a function that returns a result in an applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the elements.",
			"The applicative context.",
			"The type of the input value.",
			"The type of the error value.",
			"The type of the success value."
		)]
		///
		#[document_parameters("The function to apply.", "The vector to partition.")]
		///
		#[document_returns("The partitioned vector wrapped in the applicative context.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let y = wilt::<VecBrand, OptionBrand, _, _, _>(
		/// 	|a| Some(if a % 2 == 0 { Ok(a) } else { Err(a) }),
		/// 	x,
		/// );
		/// assert_eq!(y, Some((vec![1, 3], vec![2, 4])));
		/// ```
		fn wilt<'a, M: Applicative, A: 'a + Clone, E: 'a + Clone, O: 'a + Clone>(
			func: impl Fn(A) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
			+ 'a,
			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, E>),
			Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
		),
	>)
		where
			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, {
			ta.into_iter().fold(M::pure((Vec::new(), Vec::new())), |acc, x| {
				M::lift2(
					|mut pair, res| {
						match res {
							Ok(o) => pair.1.push(o),
							Err(e) => pair.0.push(e),
						}
						pair
					},
					acc,
					func(x),
				)
			})
		}

		/// Maps a function over a vector and filters out `None` results in an applicative context.
		///
		/// This method maps a function over a vector and filters out `None` results in an applicative context.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The applicative context.",
			"The type of the elements in the input structure.",
			"The type of the result of applying the function."
		)]
		///
		#[document_parameters(
			"The function to apply to each element, returning an `Option` in an applicative context.",
			"The vector to filter and map."
		)]
		///
		#[document_returns("The filtered and mapped vector wrapped in the applicative context.")]
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		OptionBrand,
		/// 		VecBrand,
		/// 	},
		/// 	functions::*,
		/// };
		///
		/// let x = vec![1, 2, 3, 4];
		/// let y = wither::<VecBrand, OptionBrand, _, _>(
		/// 	|a| Some(if a % 2 == 0 { Some(a * 2) } else { None }),
		/// 	x,
		/// );
		/// assert_eq!(y, Some(vec![4, 8]));
		/// ```
		fn wither<'a, M: Applicative, A: 'a + Clone, B: 'a + Clone>(
			func: impl Fn(A) -> Apply!(<M as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Option<B>>) + 'a,
			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
			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, {
			ta.into_iter().fold(M::pure(Vec::new()), |acc, x| {
				M::lift2(
					|mut v, opt_b| {
						if let Some(b) = opt_b {
							v.push(b);
						}
						v
					},
					acc,
					func(x),
				)
			})
		}
	}

	/// Cooperative extension for [`Vec`], ported from PureScript's `Extend Array` instance.
	///
	/// `extend(f, vec)` produces a new vector where each element at index `i` is
	/// `f` applied to the suffix `vec[i..]`. This is the dual of [`Semimonad::bind`]:
	/// where `bind` feeds each element into a function that produces a new context,
	/// `extend` feeds each suffix (context) into a function that produces a single value.
	///
	/// Requires `A: Clone` because suffixes are materialized as owned vectors.
	impl Extend for VecBrand {
		/// Extends a local context-dependent computation to a global computation over
		/// [`Vec`].
		///
		/// Applies `f` to every suffix of the input vector. For a vector
		/// `[a, b, c]`, the result is `[f([a, b, c]), f([b, c]), f([c])]`.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the values.",
			"The type of the elements in the vector.",
			"The result type of the extension function."
		)]
		///
		#[document_parameters(
			"The function that consumes a suffix vector and produces a value.",
			"The vector to extend over."
		)]
		///
		#[document_returns(
			"A new vector containing the results of applying the function to each suffix."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::*,
		/// 	functions::*,
		/// };
		///
		/// let result = extend::<VecBrand, _, _>(|v: Vec<i32>| v.iter().sum::<i32>(), vec![1, 2, 3]);
		/// assert_eq!(result, vec![6, 5, 3]);
		/// ```
		fn extend<'a, A: 'a + Clone, B: 'a>(
			f: impl Fn(Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)) -> B + 'a,
			wa: 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>) {
			(0 .. wa.len()).map(|i| f(wa.get(i ..).unwrap_or_default().to_vec())).collect()
		}
	}

	impl MonadRec for VecBrand {
		/// Performs tail-recursive monadic computation over [`Vec`].
		///
		/// Since `Vec` represents nondeterminism, this performs a breadth-first
		/// expansion: each iteration maps all current `Loop` states through the step
		/// function, collecting `Done` results as they appear. The computation
		/// terminates when no `Loop` values remain.
		#[document_signature]
		///
		#[document_type_parameters(
			"The lifetime of the computation.",
			"The type of the initial value and loop state.",
			"The type of the result."
		)]
		///
		#[document_parameters("The step function.", "The initial value.")]
		///
		#[document_returns("A vector of all completed results.")]
		///
		#[document_examples]
		///
		/// ```
		/// use {
		/// 	core::ops::ControlFlow,
		/// 	fp_library::{
		/// 		brands::*,
		/// 		functions::*,
		/// 		types::*,
		/// 	},
		/// };
		///
		/// // Branch into two paths, each running until done
		/// let result = tail_rec_m::<VecBrand, _, _>(
		/// 	|n| {
		/// 		if n < 3 {
		/// 			vec![ControlFlow::Continue(n + 1), ControlFlow::Break(n * 10)]
		/// 		} else {
		/// 			vec![ControlFlow::Break(n * 10)]
		/// 		}
		/// 	},
		/// 	0,
		/// );
		/// // Starting from 0: branches at 0,1,2; done at 3
		/// assert_eq!(result, vec![0, 10, 20, 30]);
		/// ```
		fn tail_rec_m<'a, A: 'a, B: 'a>(
			func: impl Fn(
				A,
			)
				-> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, ControlFlow<B, A>>)
			+ 'a,
			initial: A,
		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) {
			let mut done: Vec<B> = Vec::new();
			let mut pending: Vec<A> = vec![initial];
			while !pending.is_empty() {
				let mut next_pending: Vec<A> = Vec::new();
				for a in pending {
					for step in func(a) {
						match step {
							ControlFlow::Continue(next) => next_pending.push(next),
							ControlFlow::Break(b) => done.push(b),
						}
					}
				}
				pending = next_pending;
			}
			done
		}
	}
}

#[cfg(test)]
mod tests {

	use {
		crate::{
			brands::*,
			classes::CloneableFn,
			functions::*,
		},
		quickcheck_macros::quickcheck,
	};

	// Functor Laws

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

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

	// Applicative Laws

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

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

	/// Tests the composition law for Applicative.
	#[quickcheck]
	fn applicative_composition(
		w: Vec<i32>,
		u_seeds: Vec<i32>,
		v_seeds: Vec<i32>,
	) -> bool {
		let u_fns: Vec<_> = u_seeds
			.iter()
			.map(|&i| <RcFnBrand as CloneableFn>::new(move |x: i32| x.wrapping_add(i)))
			.collect();
		let v_fns: Vec<_> = v_seeds
			.iter()
			.map(|&i| <RcFnBrand as CloneableFn>::new(move |x: i32| x.wrapping_mul(i)))
			.collect();

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

		// LHS: pure(compose) <*> u <*> v <*> w
		// equivalent to (u . v) <*> w
		// We construct (u . v) manually as the cartesian product of compositions
		let uv_fns: Vec<_> = u_fns
			.iter()
			.flat_map(|uf| {
				v_fns.iter().map(move |vf| {
					let uf = uf.clone();
					let vf = vf.clone();
					<RcFnBrand as CloneableFn>::new(move |x| uf(vf(x)))
				})
			})
			.collect();

		let lhs = apply::<RcFnBrand, VecBrand, _, _>(uv_fns, 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 = vec![<RcFnBrand as CloneableFn>::new(f)];

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

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

		lhs == rhs
	}

	// Semigroup Laws

	/// Tests the associativity law for Semigroup.
	#[quickcheck]
	fn semigroup_associativity(
		a: Vec<i32>,
		b: Vec<i32>,
		c: Vec<i32>,
	) -> bool {
		append(a.clone(), append(b.clone(), c.clone())) == append(append(a, b), c)
	}

	// Monoid Laws

	/// Tests the left identity law for Monoid.
	#[quickcheck]
	fn monoid_left_identity(a: Vec<i32>) -> bool {
		append(empty::<Vec<i32>>(), a.clone()) == a
	}

	/// Tests the right identity law for Monoid.
	#[quickcheck]
	fn monoid_right_identity(a: Vec<i32>) -> bool {
		append(a.clone(), empty::<Vec<i32>>()) == a
	}

	// Monad Laws

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

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

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

	// Edge Cases

	/// Tests `map` on an empty vector.
	#[test]
	fn map_empty() {
		assert_eq!(map::<VecBrand, _, _>(|x: i32| x + 1, vec![] as Vec<i32>), vec![] as Vec<i32>);
	}

	/// Tests `bind` on an empty vector.
	#[test]
	fn bind_empty() {
		assert_eq!(
			bind::<VecBrand, _, _>(vec![] as Vec<i32>, |x: i32| vec![x + 1]),
			vec![] as Vec<i32>
		);
	}

	/// Tests `bind` returning an empty vector.
	#[test]
	fn bind_returning_empty() {
		assert_eq!(
			bind::<VecBrand, _, _>(vec![1, 2, 3], |_| vec![] as Vec<i32>),
			vec![] as Vec<i32>
		);
	}

	/// Tests `fold_right` on an empty vector.
	#[test]
	fn fold_right_empty() {
		assert_eq!(
			crate::classes::foldable::fold_right::<RcFnBrand, VecBrand, _, _>(
				|x: i32, acc| x + acc,
				0,
				vec![]
			),
			0
		);
	}

	/// Tests `fold_left` on an empty vector.
	#[test]
	fn fold_left_empty() {
		assert_eq!(
			crate::classes::foldable::fold_left::<RcFnBrand, VecBrand, _, _>(
				|acc, x: i32| acc + x,
				0,
				vec![]
			),
			0
		);
	}

	/// Tests `traverse` on an empty vector.
	#[test]
	fn traverse_empty() {
		use crate::brands::OptionBrand;
		assert_eq!(
			crate::classes::traversable::traverse::<VecBrand, _, _, OptionBrand>(
				|x: i32| Some(x + 1),
				vec![]
			),
			Some(vec![])
		);
	}

	/// Tests `traverse` returning an empty vector.
	#[test]
	fn traverse_returning_empty() {
		use crate::brands::OptionBrand;
		assert_eq!(
			crate::classes::traversable::traverse::<VecBrand, _, _, OptionBrand>(
				|_: i32| None::<i32>,
				vec![1, 2, 3]
			),
			None
		);
	}

	/// Tests `construct` with an empty tail.
	#[test]
	fn construct_empty_tail() {
		assert_eq!(VecBrand::construct(1, vec![]), vec![1]);
	}

	/// Tests `deconstruct` on an empty slice.
	#[test]
	fn deconstruct_empty() {
		assert_eq!(VecBrand::deconstruct::<i32>(&[]), None);
	}

	// Parallel Trait Tests

	/// Tests `par_map` on a vector.
	#[test]
	fn par_map_basic() {
		let v = vec![1, 2, 3];
		let result: Vec<i32> = par_map::<VecBrand, _, _>(|x: i32| x * 2, v);
		assert_eq!(result, vec![2, 4, 6]);
	}

	/// Tests `par_filter` on a vector.
	#[test]
	fn par_filter_basic() {
		let v = vec![1, 2, 3, 4, 5];
		let result: Vec<i32> = par_filter::<VecBrand, _>(|x: &i32| x % 2 == 0, v);
		assert_eq!(result, vec![2, 4]);
	}

	/// Tests `par_filter_map` on a vector.
	#[test]
	fn par_filter_map_basic() {
		let v = vec![1, 2, 3, 4, 5];
		let result: Vec<i32> = par_filter_map::<VecBrand, _, _>(
			|x: i32| if x % 2 == 0 { Some(x * 10) } else { None },
			v,
		);
		assert_eq!(result, vec![20, 40]);
	}

	/// Tests `par_compact` on a vector of options.
	#[test]
	fn par_compact_basic() {
		let v = vec![Some(1), None, Some(3), None, Some(5)];
		let result: Vec<i32> = par_compact::<VecBrand, _>(v);
		assert_eq!(result, vec![1, 3, 5]);
	}

	/// Tests `par_separate` on a vector of results.
	#[test]
	fn par_separate_basic() {
		let v: Vec<Result<i32, &str>> = vec![Ok(1), Err("a"), Ok(3), Err("b")];
		let (errs, oks): (Vec<&str>, Vec<i32>) = par_separate::<VecBrand, _, _>(v);
		assert_eq!(errs, vec!["a", "b"]);
		assert_eq!(oks, vec![1, 3]);
	}

	/// Tests `par_map_with_index` on a vector.
	#[test]
	fn par_map_with_index_basic() {
		let v = vec![10, 20, 30];
		let result: Vec<i32> = par_map_with_index::<VecBrand, _, _>(|i, x: i32| x + i as i32, v);
		assert_eq!(result, vec![10, 21, 32]);
	}

	/// Tests `par_fold_map` on an empty vector.
	#[test]
	fn par_fold_map_empty() {
		let v: Vec<i32> = vec![];
		assert_eq!(par_fold_map::<VecBrand, _, _>(|x: i32| x.to_string(), v), "".to_string());
	}

	/// Tests `par_fold_map` on multiple elements.
	#[test]
	fn par_fold_map_multiple() {
		let v = vec![1, 2, 3];
		assert_eq!(par_fold_map::<VecBrand, _, _>(|x: i32| x.to_string(), v), "123".to_string());
	}

	/// Tests `par_fold_map_with_index` on a vector.
	#[test]
	fn par_fold_map_with_index_basic() {
		let v = vec![10, 20, 30];
		let result: String =
			par_fold_map_with_index::<VecBrand, _, _>(|i, x: i32| format!("{i}:{x}"), v);
		assert_eq!(result, "0:101:202:30");
	}

	// Filterable Laws

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

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

	/// Tests `filterMap (l <=< r) ≡ filterMap l <<< filterMap r`.
	#[quickcheck]
	fn filterable_filter_map_composition(x: Vec<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| bind::<OptionBrand, _, _>(r(i), l);

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

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

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

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

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

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

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

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

		satisfied == oks && not_satisfied == errs
	}

	// Witherable Laws

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

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

		let lhs = wilt::<VecBrand, OptionBrand, _, _, _>(p, x.clone());
		let rhs = crate::classes::functor::map::<OptionBrand, _, _>(
			separate::<VecBrand, _, _>,
			traverse::<VecBrand, _, _, OptionBrand>(p, x),
		);

		lhs == rhs
	}

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

		let lhs = wither::<VecBrand, OptionBrand, _, _>(p, x.clone());
		let rhs = crate::classes::functor::map::<OptionBrand, _, _>(
			compact::<VecBrand, _>,
			traverse::<VecBrand, _, _, OptionBrand>(p, x),
		);

		lhs == rhs
	}

	// Alt Laws

	/// Tests the associativity law for Alt.
	#[quickcheck]
	fn alt_associativity(
		x: Vec<i32>,
		y: Vec<i32>,
		z: Vec<i32>,
	) -> bool {
		alt::<VecBrand, _>(alt::<VecBrand, _>(x.clone(), y.clone()), z.clone())
			== alt::<VecBrand, _>(x, alt::<VecBrand, _>(y, z))
	}

	/// Tests the distributivity law for Alt.
	#[quickcheck]
	fn alt_distributivity(
		x: Vec<i32>,
		y: Vec<i32>,
	) -> bool {
		let f = |i: i32| i.wrapping_mul(2).wrapping_add(1);
		map::<VecBrand, _, _>(f, alt::<VecBrand, _>(x.clone(), y.clone()))
			== alt::<VecBrand, _>(map::<VecBrand, _, _>(f, x), map::<VecBrand, _, _>(f, y))
	}

	// Plus Laws

	/// Tests the left identity law for Plus.
	#[quickcheck]
	fn plus_left_identity(x: Vec<i32>) -> bool {
		alt::<VecBrand, _>(plus_empty::<VecBrand, i32>(), x.clone()) == x
	}

	/// Tests the right identity law for Plus.
	#[quickcheck]
	fn plus_right_identity(x: Vec<i32>) -> bool {
		alt::<VecBrand, _>(x.clone(), plus_empty::<VecBrand, i32>()) == x
	}

	/// Tests the annihilation law for Plus.
	#[test]
	fn plus_annihilation() {
		let f = |i: i32| i.wrapping_mul(2);
		assert_eq!(
			map::<VecBrand, _, _>(f, plus_empty::<VecBrand, i32>()),
			plus_empty::<VecBrand, i32>(),
		);
	}

	// Compactable Laws (Plus-dependent)

	/// Tests the functor identity law for Compactable.
	#[quickcheck]
	fn compactable_functor_identity(fa: Vec<i32>) -> bool {
		compact::<VecBrand, _>(map::<VecBrand, _, _>(Some, fa.clone())) == fa
	}

	/// Tests the Plus annihilation (empty) law for Compactable.
	#[test]
	fn compactable_plus_annihilation_empty() {
		assert_eq!(
			compact::<VecBrand, _>(plus_empty::<VecBrand, Option<i32>>()),
			plus_empty::<VecBrand, i32>(),
		);
	}

	/// Tests the Plus annihilation (map) law for Compactable.
	#[quickcheck]
	fn compactable_plus_annihilation_map(xs: Vec<i32>) -> bool {
		compact::<VecBrand, _>(map::<VecBrand, _, _>(|_: i32| None::<i32>, xs))
			== plus_empty::<VecBrand, i32>()
	}

	// Edge Cases

	/// Tests `compact` on an empty vector.
	#[test]
	fn compact_empty() {
		assert_eq!(compact::<VecBrand, i32>(vec![] as Vec<Option<i32>>), vec![] as Vec<i32>);
	}

	/// Tests `compact` on a vector with `None`.
	#[test]
	fn compact_with_none() {
		assert_eq!(compact::<VecBrand, i32>(vec![Some(1), None, Some(2)]), vec![1, 2]);
	}

	/// Tests `separate` on an empty vector.
	#[test]
	fn separate_empty() {
		let (errs, oks) = separate::<VecBrand, i32, i32>(vec![] as Vec<Result<i32, i32>>);
		assert_eq!(oks, vec![] as Vec<i32>);
		assert_eq!(errs, vec![] as Vec<i32>);
	}

	/// Tests `separate` on a vector with `Ok` and `Err`.
	#[test]
	fn separate_mixed() {
		let (errs, oks) = separate::<VecBrand, i32, i32>(vec![Ok(1), Err(2), Ok(3)]);
		assert_eq!(oks, vec![1, 3]);
		assert_eq!(errs, vec![2]);
	}

	/// Tests `partition_map` on an empty vector.
	#[test]
	fn partition_map_empty() {
		let (errs, oks) =
			partition_map::<VecBrand, i32, i32, _>(|x: i32| Ok::<i32, i32>(x), vec![]);
		assert_eq!(oks, vec![] as Vec<i32>);
		assert_eq!(errs, vec![] as Vec<i32>);
	}

	/// Tests `partition` on an empty vector.
	#[test]
	fn partition_empty() {
		let (not_satisfied, satisfied) = partition::<VecBrand, i32>(|x: i32| x > 0, vec![]);
		assert_eq!(satisfied, vec![] as Vec<i32>);
		assert_eq!(not_satisfied, vec![] as Vec<i32>);
	}

	/// Tests `filter_map` on an empty vector.
	#[test]
	fn filter_map_empty() {
		assert_eq!(filter_map::<VecBrand, i32, _>(|x: i32| Some(x), vec![]), vec![] as Vec<i32>);
	}

	/// Tests `filter` on an empty vector.
	#[test]
	fn filter_empty() {
		assert_eq!(filter::<VecBrand, i32>(|x: i32| x > 0, vec![]), vec![] as Vec<i32>);
	}

	/// Tests `wilt` on an empty vector.
	#[test]
	fn wilt_empty() {
		let res = wilt::<VecBrand, OptionBrand, _, _, _>(|x: i32| Some(Ok::<i32, i32>(x)), vec![]);
		assert_eq!(res, Some((vec![], vec![])));
	}

	/// Tests `wither` on an empty vector.
	#[test]
	fn wither_empty() {
		let res = wither::<VecBrand, OptionBrand, _, _>(|x: i32| Some(Some(x)), vec![]);
		assert_eq!(res, Some(vec![]));
	}

	// Parallel Trait Laws

	/// Verifies that `par_fold_map` correctly sums a large vector (100,000 elements).
	#[test]
	fn test_large_vector_par_fold_map() {
		use crate::types::Additive;

		let xs: Vec<i32> = (0 .. 100000).collect();
		let res = par_fold_map::<VecBrand, _, _>(|x: i32| Additive(x as i64), xs);
		assert_eq!(res, Additive(4999950000));
	}

	/// Property: `par_map` agrees with sequential `map`.
	#[quickcheck]
	fn prop_par_map_equals_map(xs: Vec<i32>) -> bool {
		let f = |x: i32| x.wrapping_add(1);
		let seq_res = map::<VecBrand, _, _>(f, xs.clone());
		let par_res = par_map::<VecBrand, _, _>(f, xs);
		seq_res == par_res
	}

	/// Property: `par_fold_map` agrees with sequential `fold_map`.
	#[quickcheck]
	fn prop_par_fold_map_equals_fold_map(xs: Vec<i32>) -> bool {
		use crate::types::Additive;

		let f = |x: i32| Additive(x as i64);
		let seq_res = crate::classes::foldable::fold_map::<crate::brands::RcFnBrand, VecBrand, _, _>(
			f,
			xs.clone(),
		);
		let par_res = par_fold_map::<VecBrand, _, _>(f, xs);
		seq_res == par_res
	}

	/// Property: `par_fold_map` on an empty vector returns the Monoid's empty value.
	#[quickcheck]
	fn prop_par_fold_map_empty_is_empty(xs: Vec<i32>) -> bool {
		use crate::types::Additive;

		if !xs.is_empty() {
			return true;
		}
		let par_res = par_fold_map::<VecBrand, _, _>(|x: i32| Additive(x as i64), xs);
		par_res == empty::<Additive<i64>>()
	}

	// MonadRec tests

	/// Tests the MonadRec identity law: `tail_rec_m(|a| pure(Done(a)), x) == pure(x)`.
	#[quickcheck]
	fn monad_rec_identity(x: i32) -> bool {
		use {
			crate::classes::monad_rec::tail_rec_m,
			core::ops::ControlFlow,
		};
		tail_rec_m::<VecBrand, _, _>(|a| vec![ControlFlow::Break(a)], x) == vec![x]
	}

	/// Tests a simple linear recursion via `tail_rec_m`.
	#[test]
	fn monad_rec_linear() {
		use {
			crate::classes::monad_rec::tail_rec_m,
			core::ops::ControlFlow,
		};
		// Count up to 5
		let result = tail_rec_m::<VecBrand, _, _>(
			|n| {
				if n < 5 { vec![ControlFlow::Continue(n + 1)] } else { vec![ControlFlow::Break(n)] }
			},
			0,
		);
		assert_eq!(result, vec![5]);
	}

	/// Tests branching nondeterminism via `tail_rec_m`.
	#[test]
	fn monad_rec_branching() {
		use {
			crate::classes::monad_rec::tail_rec_m,
			core::ops::ControlFlow,
		};
		// Each step either finishes or continues
		let result = tail_rec_m::<VecBrand, _, _>(
			|n: i32| {
				if n < 2 {
					vec![ControlFlow::Continue(n + 1), ControlFlow::Break(n * 100)]
				} else {
					vec![ControlFlow::Break(n * 100)]
				}
			},
			0,
		);
		// n=0: Loop(1), Done(0)
		// n=1: Loop(2), Done(100)
		// n=2: Done(200)
		assert_eq!(result, vec![0, 100, 200]);
	}

	/// Tests that `tail_rec_m` handles an empty result from the step function.
	#[test]
	fn monad_rec_empty() {
		use {
			crate::classes::monad_rec::tail_rec_m,
			core::ops::ControlFlow,
		};
		let result: Vec<i32> =
			tail_rec_m::<VecBrand, _, _>(|_n| Vec::<ControlFlow<i32, i32>>::new(), 0);
		assert_eq!(result, Vec::<i32>::new());
	}

	// Extend Laws

	/// Tests basic `extend` on `Vec`: sum of suffixes.
	#[test]
	fn extend_sum_of_suffixes() {
		use crate::classes::extend::extend;
		let result = extend::<VecBrand, _, _>(|v: Vec<i32>| v.iter().sum::<i32>(), vec![1, 2, 3]);
		assert_eq!(result, vec![6, 5, 3]);
	}

	/// Extend associativity: `extend(f, extend(g, w)) == extend(|w| f(extend(g, w)), w)`.
	#[quickcheck]
	fn extend_associativity(w: Vec<i32>) -> bool {
		use crate::classes::extend::extend;
		let g = |v: Vec<i32>| v.iter().fold(0i32, |a, b| a.wrapping_mul(2).wrapping_add(*b));
		let f = |v: Vec<i32>| v.iter().fold(0i32, |a, b| a.wrapping_add(b.wrapping_add(1)));
		let lhs = extend::<VecBrand, _, _>(f, extend::<VecBrand, _, _>(g, w.clone()));
		let rhs = extend::<VecBrand, _, _>(|w: Vec<i32>| f(extend::<VecBrand, _, _>(g, w)), w);
		lhs == rhs
	}

	/// Tests that `duplicate` produces suffixes.
	#[test]
	fn extend_duplicate_suffixes() {
		use crate::classes::extend::duplicate;
		let result = duplicate::<VecBrand, _>(vec![1, 2, 3]);
		assert_eq!(result, vec![vec![1, 2, 3], vec![2, 3], vec![3]]);
	}

	/// Tests `extend` on an empty vector.
	#[test]
	fn extend_empty() {
		use crate::classes::extend::extend;
		let result =
			extend::<VecBrand, _, _>(|v: Vec<i32>| v.iter().sum::<i32>(), Vec::<i32>::new());
		assert_eq!(result, Vec::<i32>::new());
	}

	/// Tests `extend` on a singleton vector.
	#[test]
	fn extend_singleton() {
		use crate::classes::extend::extend;
		let result = extend::<VecBrand, _, _>(|v: Vec<i32>| v.iter().sum::<i32>(), vec![42]);
		assert_eq!(result, vec![42]);
	}
}