fp_library/dispatch/
compactable.rs

1//! Dispatch for compactable operations:
2//! [`Compactable`](crate::classes::Compactable) and
3//! [`RefCompactable`](crate::classes::RefCompactable).
4//!
5//! Provides the following dispatch traits and unified free functions:
6//!
7//! - [`CompactDispatch`] + [`explicit::compact`]
8//! - [`SeparateDispatch`] + [`explicit::separate`]
9//!
10//! Each routes to the appropriate trait method based on whether the container
11//! is owned or borrowed.
12//!
13//! ### Examples
14//!
15//! ```
16//! use fp_library::{
17//! 	brands::*,
18//! 	functions::explicit::*,
19//! };
20//!
21//! // compact
22//! let y = compact::<VecBrand, _, _, _>(vec![Some(1), None, Some(3)]);
23//! assert_eq!(y, vec![1, 3]);
24//!
25//! // separate
26//! let (errs, oks) = separate::<VecBrand, _, _, _, _>(vec![Ok(1), Err(2), Ok(3)]);
27//! assert_eq!(oks, vec![1, 3]);
28//! assert_eq!(errs, vec![2]);
29//! ```
30
31#[fp_macros::document_module]
32pub(crate) mod inner {
33	use {
34		crate::{
35			brands::OptionBrand,
36			classes::{
37				Compactable,
38				RefCompactable,
39			},
40			dispatch::{
41				Ref,
42				Val,
43			},
44			kinds::*,
45		},
46		fp_macros::*,
47	};
48
49	// -- CompactDispatch --
50
51	/// Trait that routes a compact operation to the appropriate type class method.
52	///
53	/// The `Marker` type parameter is an implementation detail resolved by
54	/// the compiler from the container type; callers never specify it directly.
55	/// Owned containers resolve to [`Val`], borrowed containers resolve to [`Ref`].
56	#[document_type_parameters(
57		"The lifetime of the values.",
58		"The brand of the compactable.",
59		"The type of the value(s) inside the `Option` wrappers.",
60		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
61	)]
62	#[document_parameters("The container implementing this dispatch.")]
63	pub trait CompactDispatch<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a, Marker> {
64		/// Perform the dispatched compact operation.
65		#[document_signature]
66		///
67		#[document_returns(
68			"A new container with `None` values removed and `Some` values unwrapped."
69		)]
70		#[document_examples]
71		///
72		/// ```
73		/// use fp_library::{
74		/// 	brands::*,
75		/// 	functions::explicit::*,
76		/// };
77		///
78		/// let result = compact::<VecBrand, _, _, _>(vec![Some(1), None, Some(3)]);
79		/// assert_eq!(result, vec![1, 3]);
80		/// ```
81		fn dispatch(self) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>);
82	}
83
84	/// Routes owned containers to [`Compactable::compact`].
85	#[document_type_parameters(
86		"The lifetime of the values.",
87		"The brand of the compactable.",
88		"The type of the value(s) inside the `Option` wrappers."
89	)]
90	#[document_parameters("The owned container of `Option` values.")]
91	impl<'a, Brand, A> CompactDispatch<'a, Brand, A, Val> for Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Apply!(<OptionBrand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)>)
92	where
93		Brand: Compactable,
94		A: 'a,
95	{
96		#[document_signature]
97		///
98		#[document_returns(
99			"A new container with `None` values removed and `Some` values unwrapped."
100		)]
101		#[document_examples]
102		///
103		/// ```
104		/// use fp_library::{
105		/// 	brands::*,
106		/// 	functions::explicit::*,
107		/// };
108		///
109		/// let result = compact::<VecBrand, _, _, _>(vec![Some(1), None, Some(3)]);
110		/// assert_eq!(result, vec![1, 3]);
111		/// ```
112		fn dispatch(self) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
113			Brand::compact(self)
114		}
115	}
116
117	/// Routes borrowed containers to [`RefCompactable::ref_compact`].
118	#[document_type_parameters(
119		"The lifetime of the values.",
120		"The brand of the compactable.",
121		"The type of the value(s) inside the `Option` wrappers."
122	)]
123	#[document_parameters("The borrowed container of `Option` values.")]
124	impl<'a, Brand, A> CompactDispatch<'a, Brand, A, Ref> for &Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Apply!(<OptionBrand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)>)
125	where
126		Brand: RefCompactable,
127		A: 'a + Clone,
128	{
129		#[document_signature]
130		///
131		#[document_returns(
132			"A new container with `None` values removed and `Some` values unwrapped."
133		)]
134		#[document_examples]
135		///
136		/// ```
137		/// use fp_library::{
138		/// 	brands::*,
139		/// 	functions::explicit::*,
140		/// };
141		///
142		/// let v = vec![Some(1), None, Some(3)];
143		/// let result = compact::<VecBrand, _, _, _>(&v);
144		/// assert_eq!(result, vec![1, 3]);
145		/// ```
146		fn dispatch(self) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
147			Brand::ref_compact(self)
148		}
149	}
150
151	// -- SeparateDispatch --
152
153	/// Trait that routes a separate operation to the appropriate type class method.
154	///
155	/// The `Marker` type parameter is an implementation detail resolved by
156	/// the compiler from the container type; callers never specify it directly.
157	/// Owned containers resolve to [`Val`], borrowed containers resolve to [`Ref`].
158	#[document_type_parameters(
159		"The lifetime of the values.",
160		"The brand of the compactable.",
161		"The error type inside the `Result` wrappers.",
162		"The success type inside the `Result` wrappers.",
163		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
164	)]
165	#[document_parameters("The container implementing this dispatch.")]
166	pub trait SeparateDispatch<'a, Brand: Kind_cdc7cd43dac7585f, E: 'a, O: 'a, Marker> {
167		/// Perform the dispatched separate operation.
168		#[document_signature]
169		///
170		#[document_returns("A tuple of two containers: `Err` values and `Ok` values.")]
171		#[document_examples]
172		///
173		/// ```
174		/// use fp_library::{
175		/// 	brands::*,
176		/// 	functions::explicit::*,
177		/// };
178		///
179		/// let (errs, oks) = separate::<VecBrand, _, _, _, _>(vec![Ok(1), Err(2), Ok(3)]);
180		/// assert_eq!(oks, vec![1, 3]);
181		/// assert_eq!(errs, vec![2]);
182		/// ```
183		fn dispatch(
184			self
185		) -> (
186			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
187			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
188		);
189	}
190
191	/// Routes owned containers to [`Compactable::separate`].
192	#[document_type_parameters(
193		"The lifetime of the values.",
194		"The brand of the compactable.",
195		"The error type inside the `Result` wrappers.",
196		"The success type inside the `Result` wrappers."
197	)]
198	#[document_parameters("The owned container of `Result` values.")]
199	impl<'a, Brand, E, O> SeparateDispatch<'a, Brand, E, O, Val> for Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
200	where
201		Brand: Compactable,
202		E: 'a,
203		O: 'a,
204	{
205		#[document_signature]
206		///
207		#[document_returns("A tuple of two containers: `Err` values and `Ok` values.")]
208		#[document_examples]
209		///
210		/// ```
211		/// use fp_library::{
212		/// 	brands::*,
213		/// 	functions::explicit::*,
214		/// };
215		///
216		/// let (errs, oks) = separate::<VecBrand, _, _, _, _>(vec![Ok(1), Err(2), Ok(3)]);
217		/// assert_eq!(oks, vec![1, 3]);
218		/// assert_eq!(errs, vec![2]);
219		/// ```
220		fn dispatch(
221			self
222		) -> (
223			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
224			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
225		) {
226			Brand::separate(self)
227		}
228	}
229
230	/// Routes borrowed containers to [`RefCompactable::ref_separate`].
231	#[document_type_parameters(
232		"The lifetime of the values.",
233		"The brand of the compactable.",
234		"The error type inside the `Result` wrappers.",
235		"The success type inside the `Result` wrappers."
236	)]
237	#[document_parameters("The borrowed container of `Result` values.")]
238	impl<'a, Brand, E, O> SeparateDispatch<'a, Brand, E, O, Ref> for &Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, Result<O, E>>)
239	where
240		Brand: RefCompactable,
241		E: 'a + Clone,
242		O: 'a + Clone,
243	{
244		#[document_signature]
245		///
246		#[document_returns("A tuple of two containers: `Err` values and `Ok` values.")]
247		#[document_examples]
248		///
249		/// ```
250		/// use fp_library::{
251		/// 	brands::*,
252		/// 	functions::explicit::*,
253		/// };
254		///
255		/// let v: Vec<Result<i32, i32>> = vec![Ok(1), Err(2), Ok(3)];
256		/// let (errs, oks) = separate::<VecBrand, _, _, _, _>(&v);
257		/// assert_eq!(oks, vec![1, 3]);
258		/// assert_eq!(errs, vec![2]);
259		/// ```
260		fn dispatch(
261			self
262		) -> (
263			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
264			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
265		) {
266			Brand::ref_separate(self)
267		}
268	}
269
270	// -- Inference wrappers --
271
272	/// Removes `None` values from a container of `Option`s, inferring the brand
273	/// from the container type.
274	///
275	/// The `Brand` type parameter is inferred from the concrete type of `fa`
276	/// via the `InferableBrand` trait. Both owned and borrowed containers are supported.
277	///
278	/// For types with multiple brands, use
279	/// [`explicit::compact`](crate::functions::explicit::compact) with a turbofish.
280	#[document_signature]
281	///
282	#[document_type_parameters(
283		"The lifetime of the values.",
284		"The container type (owned or borrowed). Brand is inferred from this.",
285		"The type of the value(s) inside the `Option` wrappers.",
286		"The brand, inferred via InferableBrand from FA and the element type."
287	)]
288	///
289	#[document_parameters("The container of `Option` values (owned or borrowed).")]
290	///
291	#[document_returns("A new container with `None` values removed and `Some` values unwrapped.")]
292	#[document_examples]
293	///
294	/// ```
295	/// use fp_library::functions::*;
296	///
297	/// assert_eq!(compact(vec![Some(1), None, Some(3)]), vec![1, 3]);
298	///
299	/// let v = vec![Some(1), None, Some(3)];
300	/// assert_eq!(compact(&v), vec![1, 3]);
301	/// ```
302	pub fn compact<'a, FA, A: 'a, Brand>(fa: FA) -> <Brand as Kind_cdc7cd43dac7585f>::Of<'a, A>
303	where
304		Brand: Kind_cdc7cd43dac7585f,
305		FA: InferableBrand_cdc7cd43dac7585f<'a, Brand, Option<A>>
306			+ CompactDispatch<
307				'a,
308				Brand,
309				A,
310				<FA as InferableBrand_cdc7cd43dac7585f<'a, Brand, Option<A>>>::Marker,
311			>, {
312		fa.dispatch()
313	}
314
315	/// Separates a container of `Result` values into two containers, inferring
316	/// the brand from the container type.
317	///
318	/// The `Brand` type parameter is inferred from the concrete type of `fa`
319	/// via the `InferableBrand` trait. Both owned and borrowed containers are supported.
320	///
321	/// For types with multiple brands, use
322	/// [`explicit::separate`](crate::functions::explicit::separate) with a turbofish.
323	#[document_signature]
324	///
325	#[document_type_parameters(
326		"The lifetime of the values.",
327		"The container type (owned or borrowed). Brand is inferred from this.",
328		"The error type inside the `Result` wrappers.",
329		"The success type inside the `Result` wrappers.",
330		"The brand, inferred via InferableBrand from FA and the element type."
331	)]
332	///
333	#[document_parameters("The container of `Result` values (owned or borrowed).")]
334	///
335	#[document_returns("A tuple of two containers: `Err` values and `Ok` values.")]
336	#[document_examples]
337	///
338	/// ```
339	/// use fp_library::functions::*;
340	///
341	/// let (errs, oks) = separate(vec![Ok(1), Err(2), Ok(3)]);
342	/// assert_eq!(oks, vec![1, 3]);
343	/// assert_eq!(errs, vec![2]);
344	/// ```
345	pub fn separate<'a, FA, E: 'a, O: 'a, Brand>(
346		fa: FA
347	) -> (<Brand as Kind_cdc7cd43dac7585f>::Of<'a, E>, <Brand as Kind_cdc7cd43dac7585f>::Of<'a, O>)
348	where
349		Brand: Kind_cdc7cd43dac7585f,
350		FA: InferableBrand_cdc7cd43dac7585f<'a, Brand, Result<O, E>>
351			+ SeparateDispatch<
352				'a,
353				Brand,
354				E,
355				O,
356				<FA as InferableBrand_cdc7cd43dac7585f<'a, Brand, Result<O, E>>>::Marker,
357			>, {
358		fa.dispatch()
359	}
360
361	// -- Explicit dispatch free functions --
362
363	/// Explicit dispatch functions requiring a Brand turbofish.
364	///
365	/// For most use cases, prefer the inference-enabled wrappers from
366	/// [`functions`](crate::functions).
367	pub mod explicit {
368		use super::*;
369
370		/// Removes `None` values from a container of `Option`s, unwrapping the `Some` values.
371		///
372		/// Dispatches to either [`Compactable::compact`] or [`RefCompactable::ref_compact`]
373		/// based on whether the container is owned or borrowed.
374		///
375		/// The dispatch is resolved at compile time with no runtime cost.
376		#[document_signature]
377		///
378		#[document_type_parameters(
379			"The lifetime of the values.",
380			"The brand of the compactable.",
381			"The type of the value(s) inside the `Option` wrappers.",
382			"The container type (owned or borrowed), inferred from the argument.",
383			"Dispatch marker type, inferred automatically."
384		)]
385		///
386		#[document_parameters("The container of `Option` values (owned or borrowed).")]
387		///
388		#[document_returns(
389			"A new container with `None` values removed and `Some` values unwrapped."
390		)]
391		///
392		#[document_examples]
393		///
394		/// ```
395		/// use fp_library::{
396		/// 	brands::*,
397		/// 	functions::explicit::*,
398		/// };
399		///
400		/// // Owned
401		/// let y = compact::<VecBrand, _, _, _>(vec![Some(1), None, Some(3)]);
402		/// assert_eq!(y, vec![1, 3]);
403		///
404		/// // By-ref
405		/// let v = vec![Some(1), None, Some(3)];
406		/// let y = compact::<VecBrand, _, _, _>(&v);
407		/// assert_eq!(y, vec![1, 3]);
408		/// ```
409		#[allow_named_generics]
410		pub fn compact<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a, FA, Marker>(
411			fa: FA
412		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
413		where
414			FA: CompactDispatch<'a, Brand, A, Marker>, {
415			fa.dispatch()
416		}
417
418		/// Separates a container of `Result` values into two containers.
419		///
420		/// Dispatches to either [`Compactable::separate`] or [`RefCompactable::ref_separate`]
421		/// based on whether the container is owned or borrowed.
422		///
423		/// The dispatch is resolved at compile time with no runtime cost.
424		#[document_signature]
425		///
426		#[document_type_parameters(
427			"The lifetime of the values.",
428			"The brand of the compactable.",
429			"The error type inside the `Result` wrappers.",
430			"The success type inside the `Result` wrappers.",
431			"The container type (owned or borrowed), inferred from the argument.",
432			"Dispatch marker type, inferred automatically."
433		)]
434		///
435		#[document_parameters("The container of `Result` values (owned or borrowed).")]
436		///
437		#[document_returns("A tuple of two containers: `Err` values and `Ok` values.")]
438		///
439		#[document_examples]
440		///
441		/// ```
442		/// use fp_library::{
443		/// 	brands::*,
444		/// 	functions::explicit::*,
445		/// };
446		///
447		/// // Owned
448		/// let (errs, oks) = separate::<VecBrand, _, _, _, _>(vec![Ok(1), Err(2), Ok(3)]);
449		/// assert_eq!(oks, vec![1, 3]);
450		/// assert_eq!(errs, vec![2]);
451		///
452		/// // By-ref
453		/// let v: Vec<Result<i32, i32>> = vec![Ok(1), Err(2), Ok(3)];
454		/// let (errs, oks) = separate::<VecBrand, _, _, _, _>(&v);
455		/// assert_eq!(oks, vec![1, 3]);
456		/// assert_eq!(errs, vec![2]);
457		/// ```
458		#[allow_named_generics]
459		pub fn separate<'a, Brand: Kind_cdc7cd43dac7585f, E: 'a, O: 'a, FA, Marker>(
460			fa: FA
461		) -> (
462			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, E>),
463			Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, O>),
464		)
465		where
466			FA: SeparateDispatch<'a, Brand, E, O, Marker>, {
467			fa.dispatch()
468		}
469	}
470}
471
472pub use inner::*;
fp_library/dispatch/compactable.rs

fp_library/dispatch/
compactable.rs
