fp_library/dispatch/
filterable.rs

1//! Dispatch for filterable operations:
2//! [`Filterable`](crate::classes::Filterable) and
3//! [`RefFilterable`](crate::classes::RefFilterable).
4//!
5//! Provides the following dispatch traits and unified free functions:
6//!
7//! - [`FilterMapDispatch`] + [`explicit::filter_map`]
8//! - [`FilterDispatch`] + [`explicit::filter`]
9//! - [`PartitionDispatch`] + [`explicit::partition`]
10//! - [`PartitionMapDispatch`] + [`explicit::partition_map`]
11//!
12//! Each routes to the appropriate trait method based on the closure's argument
13//! type.
14//!
15//! ### Examples
16//!
17//! ```
18//! use fp_library::{
19//! 	brands::*,
20//! 	functions::explicit::*,
21//! };
22//!
23//! // filter_map: Owned
24//! let y =
25//! 	filter_map::<OptionBrand, _, _, _, _>(|x: i32| if x > 3 { Some(x) } else { None }, Some(5));
26//! assert_eq!(y, Some(5));
27//!
28//! // filter: Owned
29//! let y = filter::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
30//! assert_eq!(y, Some(5));
31//!
32//! // partition: Owned
33//! let (no, yes) = partition::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
34//! assert_eq!(yes, Some(5));
35//! assert_eq!(no, None);
36//!
37//! // partition_map: Owned
38//! let (errs, oks) =
39//! 	partition_map::<OptionBrand, _, _, _, _, _>(|x: i32| Ok::<i32, i32>(x * 2), Some(5));
40//! assert_eq!(errs, None);
41//! assert_eq!(oks, Some(10));
42//! ```
43
44#[fp_macros::document_module]
45pub(crate) mod inner {
46	use {
47		crate::{
48			classes::{
49				Filterable,
50				RefFilterable,
51			},
52			dispatch::{
53				Ref,
54				Val,
55			},
56			kinds::*,
57		},
58		fp_macros::*,
59	};
60
61	// -- FilterMapDispatch --
62
63	/// Trait that routes a filter_map operation to the appropriate type class method.
64	///
65	/// The `Marker` type parameter is an implementation detail resolved by
66	/// the compiler from the closure's argument type; callers never specify
67	/// it directly. The `FA` type parameter is inferred from the container
68	/// argument: owned for Val dispatch, borrowed for Ref dispatch.
69	#[document_type_parameters(
70		"The lifetime of the values.",
71		"The brand of the filterable.",
72		"The type of the value(s) inside the filterable.",
73		"The type of the result(s) of applying the function.",
74		"The container type (owned or borrowed), inferred from the argument.",
75		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
76	)]
77	#[document_parameters("The closure implementing this dispatch.")]
78	pub trait FilterMapDispatch<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a, B: 'a, FA, Marker> {
79		/// Perform the dispatched filter_map operation.
80		#[document_signature]
81		///
82		#[document_parameters("The filterable instance containing the value(s).")]
83		///
84		#[document_returns(
85			"A new filterable instance containing only the values for which the function returned `Some`."
86		)]
87		#[document_examples]
88		///
89		/// ```
90		/// use fp_library::{
91		/// 	brands::*,
92		/// 	functions::explicit::*,
93		/// };
94		///
95		/// let result = filter_map::<OptionBrand, _, _, _, _>(
96		/// 	|x: i32| if x > 3 { Some(x * 2) } else { None },
97		/// 	Some(5),
98		/// );
99		/// assert_eq!(result, Some(10));
100		/// ```
101		fn dispatch(
102			self,
103			fa: FA,
104		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>);
105	}
106
107	// -- Val: Fn(A) -> Option<B> -> Filterable::filter_map --
108
109	/// Routes `Fn(A) -> Option<B>` closures to [`Filterable::filter_map`].
110	#[document_type_parameters(
111		"The lifetime of the values.",
112		"The brand of the filterable.",
113		"The type of the value(s) inside the filterable.",
114		"The type of the result(s) of applying the function.",
115		"The closure type."
116	)]
117	#[document_parameters("The closure that takes owned values.")]
118	impl<'a, Brand, A, B, F>
119		FilterMapDispatch<
120			'a,
121			Brand,
122			A,
123			B,
124			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
125			Val,
126		> for F
127	where
128		Brand: Filterable,
129		A: 'a,
130		B: 'a,
131		F: Fn(A) -> Option<B> + 'a,
132	{
133		#[document_signature]
134		///
135		#[document_parameters("The filterable instance containing the value(s).")]
136		///
137		#[document_returns(
138			"A new filterable instance containing only the values for which the function returned `Some`."
139		)]
140		#[document_examples]
141		///
142		/// ```
143		/// use fp_library::{
144		/// 	brands::*,
145		/// 	functions::explicit::*,
146		/// };
147		///
148		/// let result = filter_map::<OptionBrand, _, _, _, _>(
149		/// 	|x: i32| if x > 3 { Some(x * 2) } else { None },
150		/// 	Some(5),
151		/// );
152		/// assert_eq!(result, Some(10));
153		/// ```
154		fn dispatch(
155			self,
156			fa: Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
157		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) {
158			Brand::filter_map(self, fa)
159		}
160	}
161
162	// -- Ref: Fn(&A) -> Option<B> -> RefFilterable::ref_filter_map --
163
164	/// Routes `Fn(&A) -> Option<B>` closures to [`RefFilterable::ref_filter_map`].
165	///
166	/// The container must be passed by reference (`&fa`).
167	#[document_type_parameters(
168		"The lifetime of the values.",
169		"The borrow lifetime.",
170		"The brand of the filterable.",
171		"The type of the value(s) inside the filterable.",
172		"The type of the result(s) of applying the function.",
173		"The closure type."
174	)]
175	#[document_parameters("The closure that takes references.")]
176	impl<'a, 'b, Brand, A, B, F>
177		FilterMapDispatch<
178			'a,
179			Brand,
180			A,
181			B,
182			&'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
183			Ref,
184		> for F
185	where
186		Brand: RefFilterable,
187		A: 'a,
188		B: 'a,
189		F: Fn(&A) -> Option<B> + 'a,
190	{
191		#[document_signature]
192		///
193		#[document_parameters("A reference to the filterable instance.")]
194		///
195		#[document_returns(
196			"A new filterable instance containing only the values for which the function returned `Some`."
197		)]
198		#[document_examples]
199		///
200		/// ```
201		/// use fp_library::{
202		/// 	brands::*,
203		/// 	functions::explicit::*,
204		/// };
205		///
206		/// let result = filter_map::<OptionBrand, _, _, _, _>(
207		/// 	|x: &i32| if *x > 3 { Some(*x * 2) } else { None },
208		/// 	&Some(5),
209		/// );
210		/// assert_eq!(result, Some(10));
211		/// ```
212		fn dispatch(
213			self,
214			fa: &'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
215		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) {
216			Brand::ref_filter_map(self, fa)
217		}
218	}
219
220	// -- FilterDispatch --
221
222	/// Trait that routes a filter operation to the appropriate type class method.
223	///
224	/// The `Marker` type parameter is an implementation detail resolved by
225	/// the compiler from the closure's argument type; callers never specify
226	/// it directly. The `FA` type parameter is inferred from the container
227	/// argument: owned for Val dispatch, borrowed for Ref dispatch.
228	#[document_type_parameters(
229		"The lifetime of the values.",
230		"The brand of the filterable.",
231		"The type of the value(s) inside the filterable.",
232		"The container type (owned or borrowed), inferred from the argument.",
233		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
234	)]
235	#[document_parameters("The closure implementing this dispatch.")]
236	pub trait FilterDispatch<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, FA, Marker> {
237		/// Perform the dispatched filter operation.
238		#[document_signature]
239		///
240		#[document_parameters("The filterable instance containing the value(s).")]
241		///
242		#[document_returns(
243			"A new filterable instance containing only the values for which the predicate returned `true`."
244		)]
245		#[document_examples]
246		///
247		/// ```
248		/// use fp_library::{
249		/// 	brands::*,
250		/// 	functions::explicit::*,
251		/// };
252		///
253		/// let result = filter::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
254		/// assert_eq!(result, Some(5));
255		/// ```
256		fn dispatch(
257			self,
258			fa: FA,
259		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>);
260	}
261
262	// -- Val: Fn(A) -> bool -> Filterable::filter --
263
264	/// Routes `Fn(A) -> bool` closures to [`Filterable::filter`].
265	#[document_type_parameters(
266		"The lifetime of the values.",
267		"The brand of the filterable.",
268		"The type of the value(s) inside the filterable.",
269		"The closure type."
270	)]
271	#[document_parameters("The closure that takes owned values.")]
272	impl<'a, Brand, A, F>
273		FilterDispatch<
274			'a,
275			Brand,
276			A,
277			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
278			Val,
279		> for F
280	where
281		Brand: Filterable,
282		A: 'a + Clone,
283		F: Fn(A) -> bool + 'a,
284	{
285		#[document_signature]
286		///
287		#[document_parameters("The filterable instance containing the value(s).")]
288		///
289		#[document_returns(
290			"A new filterable instance containing only the values for which the predicate returned `true`."
291		)]
292		#[document_examples]
293		///
294		/// ```
295		/// use fp_library::{
296		/// 	brands::*,
297		/// 	functions::explicit::*,
298		/// };
299		///
300		/// let result = filter::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
301		/// assert_eq!(result, Some(5));
302		/// ```
303		fn dispatch(
304			self,
305			fa: Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
306		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
307			Brand::filter(self, fa)
308		}
309	}
310
311	// -- Ref: Fn(&A) -> bool -> RefFilterable::ref_filter --
312
313	/// Routes `Fn(&A) -> bool` closures to [`RefFilterable::ref_filter`].
314	///
315	/// The container must be passed by reference (`&fa`).
316	#[document_type_parameters(
317		"The lifetime of the values.",
318		"The borrow lifetime.",
319		"The brand of the filterable.",
320		"The type of the value(s) inside the filterable.",
321		"The closure type."
322	)]
323	#[document_parameters("The closure that takes references.")]
324	impl<'a, 'b, Brand, A, F>
325		FilterDispatch<
326			'a,
327			Brand,
328			A,
329			&'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
330			Ref,
331		> for F
332	where
333		Brand: RefFilterable,
334		A: 'a + Clone,
335		F: Fn(&A) -> bool + 'a,
336	{
337		#[document_signature]
338		///
339		#[document_parameters("A reference to the filterable instance.")]
340		///
341		#[document_returns(
342			"A new filterable instance containing only the values for which the predicate returned `true`."
343		)]
344		#[document_examples]
345		///
346		/// ```
347		/// use fp_library::{
348		/// 	brands::*,
349		/// 	functions::explicit::*,
350		/// };
351		///
352		/// let result = filter::<OptionBrand, _, _, _>(|x: &i32| *x > 3, &Some(5));
353		/// assert_eq!(result, Some(5));
354		/// ```
355		fn dispatch(
356			self,
357			fa: &'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
358		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
359			Brand::ref_filter(self, fa)
360		}
361	}
362
363	// -- PartitionDispatch --
364
365	/// Trait that routes a partition operation to the appropriate type class method.
366	///
367	/// The `Marker` type parameter is an implementation detail resolved by
368	/// the compiler from the closure's argument type; callers never specify
369	/// it directly. The `FA` type parameter is inferred from the container
370	/// argument: owned for Val dispatch, borrowed for Ref dispatch.
371	#[document_type_parameters(
372		"The lifetime of the values.",
373		"The brand of the filterable.",
374		"The type of the value(s) inside the filterable.",
375		"The container type (owned or borrowed), inferred from the argument.",
376		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
377	)]
378	#[document_parameters("The closure implementing this dispatch.")]
379	pub trait PartitionDispatch<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, FA, Marker> {
380		/// Perform the dispatched partition operation.
381		#[document_signature]
382		///
383		#[document_parameters("The filterable instance containing the value(s).")]
384		///
385		#[document_returns(
386			"A tuple of two filterable instances: the first contains elements satisfying the predicate, the second contains the rest."
387		)]
388		#[document_examples]
389		///
390		/// ```
391		/// use fp_library::{
392		/// 	brands::*,
393		/// 	functions::explicit::*,
394		/// };
395		///
396		/// let (no, yes) = partition::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
397		/// assert_eq!(yes, Some(5));
398		/// assert_eq!(no, None);
399		/// ```
400		fn dispatch(
401			self,
402			fa: FA,
403		) -> (
404			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
405			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
406		);
407	}
408
409	// -- Val: Fn(A) -> bool -> Filterable::partition --
410
411	/// Routes `Fn(A) -> bool` closures to [`Filterable::partition`].
412	#[document_type_parameters(
413		"The lifetime of the values.",
414		"The brand of the filterable.",
415		"The type of the value(s) inside the filterable.",
416		"The closure type."
417	)]
418	#[document_parameters("The closure that takes owned values.")]
419	impl<'a, Brand, A, F>
420		PartitionDispatch<
421			'a,
422			Brand,
423			A,
424			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
425			Val,
426		> for F
427	where
428		Brand: Filterable,
429		A: 'a + Clone,
430		F: Fn(A) -> bool + 'a,
431	{
432		#[document_signature]
433		///
434		#[document_parameters("The filterable instance containing the value(s).")]
435		///
436		#[document_returns(
437			"A tuple of two filterable instances: the first contains elements satisfying the predicate, the second contains the rest."
438		)]
439		#[document_examples]
440		///
441		/// ```
442		/// use fp_library::{
443		/// 	brands::*,
444		/// 	functions::explicit::*,
445		/// };
446		///
447		/// let (no, yes) = partition::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
448		/// assert_eq!(yes, Some(5));
449		/// assert_eq!(no, None);
450		/// ```
451		fn dispatch(
452			self,
453			fa: Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
454		) -> (
455			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
456			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
457		) {
458			Brand::partition(self, fa)
459		}
460	}
461
462	// -- Ref: Fn(&A) -> bool -> RefFilterable::ref_partition --
463
464	/// Routes `Fn(&A) -> bool` closures to [`RefFilterable::ref_partition`].
465	///
466	/// The container must be passed by reference (`&fa`).
467	#[document_type_parameters(
468		"The lifetime of the values.",
469		"The borrow lifetime.",
470		"The brand of the filterable.",
471		"The type of the value(s) inside the filterable.",
472		"The closure type."
473	)]
474	#[document_parameters("The closure that takes references.")]
475	impl<'a, 'b, Brand, A, F>
476		PartitionDispatch<
477			'a,
478			Brand,
479			A,
480			&'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
481			Ref,
482		> for F
483	where
484		Brand: RefFilterable,
485		A: 'a + Clone,
486		F: Fn(&A) -> bool + 'a,
487	{
488		#[document_signature]
489		///
490		#[document_parameters("A reference to the filterable instance.")]
491		///
492		#[document_returns(
493			"A tuple of two filterable instances: the first contains elements satisfying the predicate, the second contains the rest."
494		)]
495		#[document_examples]
496		///
497		/// ```
498		/// use fp_library::{
499		/// 	brands::*,
500		/// 	functions::explicit::*,
501		/// };
502		///
503		/// let (no, yes) = partition::<OptionBrand, _, _, _>(|x: &i32| *x > 3, &Some(5));
504		/// assert_eq!(yes, Some(5));
505		/// assert_eq!(no, None);
506		/// ```
507		fn dispatch(
508			self,
509			fa: &'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
510		) -> (
511			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
512			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
513		) {
514			Brand::ref_partition(self, fa)
515		}
516	}
517
518	// -- PartitionMapDispatch --
519
520	/// Trait that routes a partition_map operation to the appropriate type class method.
521	///
522	/// The `Marker` type parameter is an implementation detail resolved by
523	/// the compiler from the closure's argument type; callers never specify
524	/// it directly. The `FA` type parameter is inferred from the container
525	/// argument: owned for Val dispatch, borrowed for Ref dispatch.
526	#[document_type_parameters(
527		"The lifetime of the values.",
528		"The brand of the filterable.",
529		"The type of the value(s) inside the filterable.",
530		"The error type produced by the partitioning function.",
531		"The success type produced by the partitioning function.",
532		"The container type (owned or borrowed), inferred from the argument.",
533		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
534	)]
535	#[document_parameters("The closure implementing this dispatch.")]
536	pub trait PartitionMapDispatch<
537		'a,
538		Brand: Kind_cdc7cd43dac7585f,
539		A: 'a,
540		E: 'a,
541		O: 'a,
542		FA,
543		Marker,
544	> {
545		/// Perform the dispatched partition_map operation.
546		#[document_signature]
547		///
548		#[document_parameters("The filterable instance containing the value(s).")]
549		///
550		#[document_returns(
551			"A tuple of two filterable instances: the first contains the `Err` values, the second contains the `Ok` values."
552		)]
553		#[document_examples]
554		///
555		/// ```
556		/// use fp_library::{
557		/// 	brands::*,
558		/// 	functions::explicit::*,
559		/// };
560		///
561		/// let (errs, oks) =
562		/// 	partition_map::<OptionBrand, _, _, _, _, _>(|x: i32| Ok::<i32, i32>(x * 2), Some(5));
563		/// assert_eq!(errs, None);
564		/// assert_eq!(oks, Some(10));
565		/// ```
566		fn dispatch(
567			self,
568			fa: FA,
569		) -> (
570			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
571			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
572		);
573	}
574
575	// -- Val: Fn(A) -> Result<O, E> -> Filterable::partition_map --
576
577	/// Routes `Fn(A) -> Result<O, E>` closures to [`Filterable::partition_map`].
578	#[document_type_parameters(
579		"The lifetime of the values.",
580		"The brand of the filterable.",
581		"The type of the value(s) inside the filterable.",
582		"The error type produced by the partitioning function.",
583		"The success type produced by the partitioning function.",
584		"The closure type."
585	)]
586	#[document_parameters("The closure that takes owned values.")]
587	impl<'a, Brand, A, E, O, F>
588		PartitionMapDispatch<
589			'a,
590			Brand,
591			A,
592			E,
593			O,
594			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
595			Val,
596		> for F
597	where
598		Brand: Filterable,
599		A: 'a,
600		E: 'a,
601		O: 'a,
602		F: Fn(A) -> Result<O, E> + 'a,
603	{
604		#[document_signature]
605		///
606		#[document_parameters("The filterable instance containing the value(s).")]
607		///
608		#[document_returns(
609			"A tuple of two filterable instances: the first contains the `Err` values, the second contains the `Ok` values."
610		)]
611		#[document_examples]
612		///
613		/// ```
614		/// use fp_library::{
615		/// 	brands::*,
616		/// 	functions::explicit::*,
617		/// };
618		///
619		/// let (errs, oks) =
620		/// 	partition_map::<OptionBrand, _, _, _, _, _>(|x: i32| Ok::<i32, i32>(x * 2), Some(5));
621		/// assert_eq!(errs, None);
622		/// assert_eq!(oks, Some(10));
623		/// ```
624		fn dispatch(
625			self,
626			fa: Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
627		) -> (
628			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
629			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
630		) {
631			Brand::partition_map(self, fa)
632		}
633	}
634
635	// -- Ref: Fn(&A) -> Result<O, E> -> RefFilterable::ref_partition_map --
636
637	/// Routes `Fn(&A) -> Result<O, E>` closures to [`RefFilterable::ref_partition_map`].
638	///
639	/// The container must be passed by reference (`&fa`).
640	#[document_type_parameters(
641		"The lifetime of the values.",
642		"The borrow lifetime.",
643		"The brand of the filterable.",
644		"The type of the value(s) inside the filterable.",
645		"The error type produced by the partitioning function.",
646		"The success type produced by the partitioning function.",
647		"The closure type."
648	)]
649	#[document_parameters("The closure that takes references.")]
650	impl<'a, 'b, Brand, A, E, O, F>
651		PartitionMapDispatch<
652			'a,
653			Brand,
654			A,
655			E,
656			O,
657			&'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
658			Ref,
659		> for F
660	where
661		Brand: RefFilterable,
662		A: 'a,
663		E: 'a,
664		O: 'a,
665		F: Fn(&A) -> Result<O, E> + 'a,
666	{
667		#[document_signature]
668		///
669		#[document_parameters("A reference to the filterable instance.")]
670		///
671		#[document_returns(
672			"A tuple of two filterable instances: the first contains the `Err` values, the second contains the `Ok` values."
673		)]
674		#[document_examples]
675		///
676		/// ```
677		/// use fp_library::{
678		/// 	brands::*,
679		/// 	functions::explicit::*,
680		/// };
681		///
682		/// let (errs, oks) =
683		/// 	partition_map::<OptionBrand, _, _, _, _, _>(|x: &i32| Ok::<i32, i32>(*x * 2), &Some(5));
684		/// assert_eq!(errs, None);
685		/// assert_eq!(oks, Some(10));
686		/// ```
687		fn dispatch(
688			self,
689			fa: &'b Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
690		) -> (
691			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
692			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
693		) {
694			Brand::ref_partition_map(self, fa)
695		}
696	}
697
698	// -- Inference wrappers --
699
700	/// Filters the values in a filterable context using a predicate, inferring the brand
701	/// from the container type.
702	///
703	/// The `Brand` type parameter is inferred from the concrete type of `fa`
704	/// via [`InferableBrand`](crate::kinds::InferableBrand_cdc7cd43dac7585f). Both owned and borrowed containers are supported.
705	///
706	/// For types with multiple brands, use
707	/// [`explicit::filter`](crate::functions::explicit::filter) with a turbofish.
708	#[document_signature]
709	///
710	#[document_type_parameters(
711		"The lifetime of the values.",
712		"The container type (owned or borrowed). Brand is inferred from this.",
713		"The type of the value(s) inside the filterable.",
714		"Dispatch marker type, inferred automatically."
715	)]
716	///
717	#[document_parameters(
718		"The predicate to apply to each value.",
719		"The filterable instance (owned or borrowed)."
720	)]
721	///
722	#[document_returns(
723		"A new filterable instance containing only the values satisfying the predicate."
724	)]
725	#[document_examples]
726	///
727	/// ```
728	/// use fp_library::functions::*;
729	///
730	/// let y = filter(|x: i32| x > 3, Some(5));
731	/// assert_eq!(y, Some(5));
732	/// ```
733	pub fn filter<'a, FA, A: 'a + Clone, Marker>(
734		f: impl FilterDispatch<'a, <FA as InferableBrand_cdc7cd43dac7585f>::Brand, A, FA, Marker>,
735		fa: FA,
736	) -> Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
737	where
738		FA: InferableBrand_cdc7cd43dac7585f, {
739		f.dispatch(fa)
740	}
741
742	/// Filters and maps the values in a filterable context, inferring the brand
743	/// from the container type.
744	///
745	/// The `Brand` type parameter is inferred from the concrete type of `fa`
746	/// via [`InferableBrand`](crate::kinds::InferableBrand_cdc7cd43dac7585f). Both owned and borrowed containers are supported.
747	///
748	/// For types with multiple brands, use
749	/// [`explicit::filter_map`](crate::functions::explicit::filter_map) with a turbofish.
750	#[document_signature]
751	///
752	#[document_type_parameters(
753		"The lifetime of the values.",
754		"The container type (owned or borrowed). Brand is inferred from this.",
755		"The type of the value(s) inside the filterable.",
756		"The type of the result(s) of applying the function.",
757		"Dispatch marker type, inferred automatically."
758	)]
759	///
760	#[document_parameters(
761		"The function to apply to each value. Returns `Some(b)` to keep or `None` to discard.",
762		"The filterable instance (owned or borrowed)."
763	)]
764	///
765	#[document_returns("A new filterable instance containing only the kept values.")]
766	#[document_examples]
767	///
768	/// ```
769	/// use fp_library::functions::*;
770	///
771	/// let y = filter_map(|x: i32| if x > 3 { Some(x) } else { None }, Some(5));
772	/// assert_eq!(y, Some(5));
773	/// ```
774	pub fn filter_map<'a, FA, A: 'a, B: 'a, Marker>(
775		f: impl FilterMapDispatch<'a, <FA as InferableBrand_cdc7cd43dac7585f>::Brand, A, B, FA, Marker>,
776		fa: FA,
777	) -> Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>)
778	where
779		FA: InferableBrand_cdc7cd43dac7585f, {
780		f.dispatch(fa)
781	}
782
783	/// Partitions the values in a filterable context using a predicate, inferring the brand
784	/// from the container type.
785	///
786	/// The `Brand` type parameter is inferred from the concrete type of `fa`
787	/// via [`InferableBrand`](crate::kinds::InferableBrand_cdc7cd43dac7585f). Both owned and borrowed containers are supported.
788	///
789	/// For types with multiple brands, use
790	/// [`explicit::partition`](crate::functions::explicit::partition) with a turbofish.
791	#[document_signature]
792	///
793	#[document_type_parameters(
794		"The lifetime of the values.",
795		"The container type (owned or borrowed). Brand is inferred from this.",
796		"The type of the value(s) inside the filterable.",
797		"Dispatch marker type, inferred automatically."
798	)]
799	///
800	#[document_parameters(
801		"The predicate to apply to each value.",
802		"The filterable instance (owned or borrowed)."
803	)]
804	///
805	#[document_returns("A tuple of two filterable instances split by the predicate.")]
806	#[document_examples]
807	///
808	/// ```
809	/// use fp_library::functions::*;
810	///
811	/// let (no, yes) = partition(|x: i32| x > 3, Some(5));
812	/// assert_eq!(yes, Some(5));
813	/// assert_eq!(no, None);
814	/// ```
815	pub fn partition<'a, FA, A: 'a + Clone, Marker>(
816		f: impl PartitionDispatch<'a, <FA as InferableBrand_cdc7cd43dac7585f>::Brand, A, FA, Marker>,
817		fa: FA,
818	) -> (
819		Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
820		Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
821	)
822	where
823		FA: InferableBrand_cdc7cd43dac7585f, {
824		f.dispatch(fa)
825	}
826
827	/// Partitions the values using a function returning `Result`, inferring the brand
828	/// from the container type.
829	///
830	/// The `Brand` type parameter is inferred from the concrete type of `fa`
831	/// via [`InferableBrand`](crate::kinds::InferableBrand_cdc7cd43dac7585f). Both owned and borrowed containers are supported.
832	///
833	/// For types with multiple brands, use
834	/// [`explicit::partition_map`](crate::functions::explicit::partition_map) with a turbofish.
835	#[document_signature]
836	///
837	#[document_type_parameters(
838		"The lifetime of the values.",
839		"The container type (owned or borrowed). Brand is inferred from this.",
840		"The type of the value(s) inside the filterable.",
841		"The error type produced by the partitioning function.",
842		"The success type produced by the partitioning function.",
843		"Dispatch marker type, inferred automatically."
844	)]
845	///
846	#[document_parameters(
847		"The function to apply to each value. Returns `Ok(o)` or `Err(e)`.",
848		"The filterable instance (owned or borrowed)."
849	)]
850	///
851	#[document_returns("A tuple of two filterable instances: `Err` values and `Ok` values.")]
852	#[document_examples]
853	///
854	/// ```
855	/// use fp_library::functions::*;
856	///
857	/// let (errs, oks) = partition_map(|x: i32| Ok::<i32, i32>(x * 2), Some(5));
858	/// assert_eq!(errs, None);
859	/// assert_eq!(oks, Some(10));
860	/// ```
861	pub fn partition_map<'a, FA, A: 'a, E: 'a, O: 'a, Marker>(
862		f: impl PartitionMapDispatch<
863			'a,
864			<FA as InferableBrand_cdc7cd43dac7585f>::Brand,
865			A,
866			E,
867			O,
868			FA,
869			Marker,
870		>,
871		fa: FA,
872	) -> (
873		Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
874		Apply!(<<FA as InferableBrand!(type Of<'a, A: 'a>: 'a;)>::Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
875	)
876	where
877		FA: InferableBrand_cdc7cd43dac7585f, {
878		f.dispatch(fa)
879	}
880
881	// -- Explicit dispatch free functions --
882
883	/// Explicit dispatch functions requiring a Brand turbofish.
884	///
885	/// For most use cases, prefer the inference-enabled wrappers from
886	/// [`functions`](crate::functions).
887	pub mod explicit {
888		use super::*;
889
890		/// Filters and maps the values in a filterable context.
891		///
892		/// Dispatches to either [`Filterable::filter_map`] or
893		/// [`RefFilterable::ref_filter_map`] based on the closure's argument type:
894		///
895		/// - If the closure takes owned values (`Fn(A) -> Option<B>`) and the
896		///   container is owned, dispatches to [`Filterable::filter_map`].
897		/// - If the closure takes references (`Fn(&A) -> Option<B>`) and the
898		///   container is borrowed (`&fa`), dispatches to
899		///   [`RefFilterable::ref_filter_map`].
900		///
901		/// The `Marker` and `FA` type parameters are inferred automatically by the
902		/// compiler from the closure's argument type and the container argument.
903		/// Callers write `filter_map::<Brand, _, _, _, _>(...)` and never need to
904		/// specify `Marker` or `FA` explicitly.
905		///
906		/// The dispatch is resolved at compile time with no runtime cost.
907		#[document_signature]
908		///
909		#[document_type_parameters(
910			"The lifetime of the values.",
911			"The brand of the filterable.",
912			"The type of the value(s) inside the filterable.",
913			"The type of the result(s) of applying the function.",
914			"The container type (owned or borrowed), inferred from the argument.",
915			"Dispatch marker type, inferred automatically."
916		)]
917		///
918		#[document_parameters(
919			"The function to apply to each value. Returns `Some(b)` to keep the value or `None` to discard it.",
920			"The filterable instance (owned for Val, borrowed for Ref)."
921		)]
922		///
923		#[document_returns(
924			"A new filterable instance containing only the values for which the function returned `Some`."
925		)]
926		///
927		#[document_examples]
928		///
929		/// ```
930		/// use fp_library::{
931		/// 	brands::*,
932		/// 	functions::explicit::*,
933		/// };
934		///
935		/// // Owned: dispatches to Filterable::filter_map
936		/// let y =
937		/// 	filter_map::<OptionBrand, _, _, _, _>(|x: i32| if x > 3 { Some(x) } else { None }, Some(5));
938		/// assert_eq!(y, Some(5));
939		///
940		/// // By-ref: dispatches to RefFilterable::ref_filter_map
941		/// let y = filter_map::<OptionBrand, _, _, _, _>(
942		/// 	|x: &i32| if *x > 3 { Some(*x) } else { None },
943		/// 	&Some(5),
944		/// );
945		/// assert_eq!(y, Some(5));
946		/// ```
947		pub fn filter_map<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a, B: 'a, FA, Marker>(
948			f: impl FilterMapDispatch<'a, Brand, A, B, FA, Marker>,
949			fa: FA,
950		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>) {
951			f.dispatch(fa)
952		}
953
954		/// Filters the values in a filterable context using a predicate.
955		///
956		/// Dispatches to either [`Filterable::filter`] or
957		/// [`RefFilterable::ref_filter`] based on the closure's argument type:
958		///
959		/// - If the closure takes owned values (`Fn(A) -> bool`) and the
960		///   container is owned, dispatches to [`Filterable::filter`].
961		/// - If the closure takes references (`Fn(&A) -> bool`) and the
962		///   container is borrowed (`&fa`), dispatches to
963		///   [`RefFilterable::ref_filter`].
964		///
965		/// The `Marker` and `FA` type parameters are inferred automatically by the
966		/// compiler from the closure's argument type and the container argument.
967		/// Callers write `filter::<Brand, _, _, _>(...)` and never need to
968		/// specify `Marker` or `FA` explicitly.
969		///
970		/// The dispatch is resolved at compile time with no runtime cost.
971		#[document_signature]
972		///
973		#[document_type_parameters(
974			"The lifetime of the values.",
975			"The brand of the filterable.",
976			"The type of the value(s) inside the filterable.",
977			"The container type (owned or borrowed), inferred from the argument.",
978			"Dispatch marker type, inferred automatically."
979		)]
980		///
981		#[document_parameters(
982			"The predicate to apply to each value. Returns `true` to keep the value or `false` to discard it.",
983			"The filterable instance (owned for Val, borrowed for Ref)."
984		)]
985		///
986		#[document_returns(
987			"A new filterable instance containing only the values for which the predicate returned `true`."
988		)]
989		///
990		#[document_examples]
991		///
992		/// ```
993		/// use fp_library::{
994		/// 	brands::*,
995		/// 	functions::explicit::*,
996		/// };
997		///
998		/// // Owned: dispatches to Filterable::filter
999		/// let y = filter::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
1000		/// assert_eq!(y, Some(5));
1001		///
1002		/// // By-ref: dispatches to RefFilterable::ref_filter
1003		/// let y = filter::<OptionBrand, _, _, _>(|x: &i32| *x > 3, &Some(5));
1004		/// assert_eq!(y, Some(5));
1005		/// ```
1006		pub fn filter<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, FA, Marker>(
1007			f: impl FilterDispatch<'a, Brand, A, FA, Marker>,
1008			fa: FA,
1009		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
1010			f.dispatch(fa)
1011		}
1012
1013		/// Partitions the values in a filterable context using a predicate.
1014		///
1015		/// Dispatches to either [`Filterable::partition`] or
1016		/// [`RefFilterable::ref_partition`] based on the closure's argument type:
1017		///
1018		/// - If the closure takes owned values (`Fn(A) -> bool`) and the
1019		///   container is owned, dispatches to [`Filterable::partition`].
1020		/// - If the closure takes references (`Fn(&A) -> bool`) and the
1021		///   container is borrowed (`&fa`), dispatches to
1022		///   [`RefFilterable::ref_partition`].
1023		///
1024		/// The `Marker` and `FA` type parameters are inferred automatically by the
1025		/// compiler from the closure's argument type and the container argument.
1026		/// Callers write `partition::<Brand, _, _, _>(...)` and never need to
1027		/// specify `Marker` or `FA` explicitly.
1028		///
1029		/// The dispatch is resolved at compile time with no runtime cost.
1030		#[document_signature]
1031		///
1032		#[document_type_parameters(
1033			"The lifetime of the values.",
1034			"The brand of the filterable.",
1035			"The type of the value(s) inside the filterable.",
1036			"The container type (owned or borrowed), inferred from the argument.",
1037			"Dispatch marker type, inferred automatically."
1038		)]
1039		///
1040		#[document_parameters(
1041			"The predicate to apply to each value. Returns `true` for the first partition or `false` for the second.",
1042			"The filterable instance (owned for Val, borrowed for Ref)."
1043		)]
1044		///
1045		#[document_returns(
1046			"A tuple of two filterable instances: the first contains elements satisfying the predicate, the second contains the rest."
1047		)]
1048		///
1049		#[document_examples]
1050		///
1051		/// ```
1052		/// use fp_library::{
1053		/// 	brands::*,
1054		/// 	functions::explicit::*,
1055		/// };
1056		///
1057		/// // Owned: dispatches to Filterable::partition
1058		/// let (no, yes) = partition::<OptionBrand, _, _, _>(|x: i32| x > 3, Some(5));
1059		/// assert_eq!(yes, Some(5));
1060		/// assert_eq!(no, None);
1061		///
1062		/// // By-ref: dispatches to RefFilterable::ref_partition
1063		/// let (no, yes) = partition::<OptionBrand, _, _, _>(|x: &i32| *x > 3, &Some(5));
1064		/// assert_eq!(yes, Some(5));
1065		/// assert_eq!(no, None);
1066		/// ```
1067		pub fn partition<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, FA, Marker>(
1068			f: impl PartitionDispatch<'a, Brand, A, FA, Marker>,
1069			fa: FA,
1070		) -> (
1071			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
1072			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
1073		) {
1074			f.dispatch(fa)
1075		}
1076
1077		/// Partitions the values in a filterable context using a function that returns `Result`.
1078		///
1079		/// Dispatches to either [`Filterable::partition_map`] or
1080		/// [`RefFilterable::ref_partition_map`] based on the closure's argument type:
1081		///
1082		/// - If the closure takes owned values (`Fn(A) -> Result<O, E>`) and the
1083		///   container is owned, dispatches to [`Filterable::partition_map`].
1084		/// - If the closure takes references (`Fn(&A) -> Result<O, E>`) and the
1085		///   container is borrowed (`&fa`), dispatches to
1086		///   [`RefFilterable::ref_partition_map`].
1087		///
1088		/// The `Marker` and `FA` type parameters are inferred automatically by the
1089		/// compiler from the closure's argument type and the container argument.
1090		/// Callers write `partition_map::<Brand, _, _, _, _, _>(...)` and never need to
1091		/// specify `Marker` or `FA` explicitly.
1092		///
1093		/// The dispatch is resolved at compile time with no runtime cost.
1094		#[document_signature]
1095		///
1096		#[document_type_parameters(
1097			"The lifetime of the values.",
1098			"The brand of the filterable.",
1099			"The type of the value(s) inside the filterable.",
1100			"The error type produced by the partitioning function.",
1101			"The success type produced by the partitioning function.",
1102			"The container type (owned or borrowed), inferred from the argument.",
1103			"Dispatch marker type, inferred automatically."
1104		)]
1105		///
1106		#[document_parameters(
1107			"The function to apply to each value. Returns `Ok(o)` for the success partition or `Err(e)` for the error partition.",
1108			"The filterable instance (owned for Val, borrowed for Ref)."
1109		)]
1110		///
1111		#[document_returns(
1112			"A tuple of two filterable instances: the first contains the `Err` values, the second contains the `Ok` values."
1113		)]
1114		///
1115		#[document_examples]
1116		///
1117		/// ```
1118		/// use fp_library::{
1119		/// 	brands::*,
1120		/// 	functions::explicit::*,
1121		/// };
1122		///
1123		/// // Owned: dispatches to Filterable::partition_map
1124		/// let (errs, oks) =
1125		/// 	partition_map::<OptionBrand, _, _, _, _, _>(|x: i32| Ok::<i32, i32>(x * 2), Some(5));
1126		/// assert_eq!(errs, None);
1127		/// assert_eq!(oks, Some(10));
1128		///
1129		/// // By-ref: dispatches to RefFilterable::ref_partition_map
1130		/// let (errs, oks) =
1131		/// 	partition_map::<OptionBrand, _, _, _, _, _>(|x: &i32| Ok::<i32, i32>(*x * 2), &Some(5));
1132		/// assert_eq!(errs, None);
1133		/// assert_eq!(oks, Some(10));
1134		/// ```
1135		pub fn partition_map<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a, E: 'a, O: 'a, FA, Marker>(
1136			f: impl PartitionMapDispatch<'a, Brand, A, E, O, FA, Marker>,
1137			fa: FA,
1138		) -> (
1139			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
1140			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
1141		) {
1142			f.dispatch(fa)
1143		}
1144	}
1145}
1146
1147pub use inner::*;
fp_library/dispatch/filterable.rs

fp_library/dispatch/
filterable.rs
