fp_library/dispatch/
alt.rs

1//! Dispatch for [`Alt::alt`](crate::classes::Alt::alt) and
2//! [`RefAlt::ref_alt`](crate::classes::RefAlt::ref_alt).
3//!
4//! Provides the [`AltDispatch`] trait and a unified [`explicit::alt`] free
5//! function that routes to the appropriate trait method based on whether the
6//! container is owned or borrowed.
7//!
8//! ### Examples
9//!
10//! ```
11//! use fp_library::{
12//! 	brands::*,
13//! 	functions::explicit::*,
14//! };
15//!
16//! // Owned: dispatches to Alt::alt
17//! let y = alt::<OptionBrand, _, _, _>(None, Some(5));
18//! assert_eq!(y, Some(5));
19//!
20//! // By-ref: dispatches to RefAlt::ref_alt
21//! let y = alt::<OptionBrand, _, _, _>(&None, &Some(5));
22//! assert_eq!(y, Some(5));
23//! ```
24
25#[fp_macros::document_module]
26pub(crate) mod inner {
27	use {
28		crate::{
29			classes::{
30				Alt,
31				RefAlt,
32			},
33			dispatch::{
34				Ref,
35				Val,
36			},
37			kinds::*,
38		},
39		fp_macros::*,
40	};
41
42	/// Trait that routes an alt operation to the appropriate type class method.
43	///
44	/// The `Marker` type parameter is an implementation detail resolved by
45	/// the compiler from the container type; callers never specify it directly.
46	/// Owned containers resolve to [`Val`], borrowed containers resolve to [`Ref`].
47	#[document_type_parameters(
48		"The lifetime of the values.",
49		"The brand of the functor.",
50		"The type of the value(s) inside the functor.",
51		"Dispatch marker type, inferred automatically. Either [`Val`](crate::dispatch::Val) or [`Ref`](crate::dispatch::Ref)."
52	)]
53	#[document_parameters("The container implementing this dispatch.")]
54	pub trait AltDispatch<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, Marker> {
55		/// Perform the dispatched alt operation.
56		#[document_signature]
57		///
58		#[document_parameters("The other container to combine with.")]
59		///
60		#[document_returns("A new container from the combination of both inputs.")]
61		#[document_examples]
62		///
63		/// ```
64		/// use fp_library::{
65		/// 	brands::*,
66		/// 	functions::explicit::*,
67		/// };
68		///
69		/// let result = alt::<OptionBrand, _, _, _>(None, Some(5));
70		/// assert_eq!(result, Some(5));
71		/// ```
72		fn dispatch(
73			self,
74			other: Self,
75		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>);
76	}
77
78	// -- Val: owned container -> Alt::alt --
79
80	/// Routes owned containers to [`Alt::alt`].
81	#[document_type_parameters(
82		"The lifetime of the values.",
83		"The brand of the functor.",
84		"The type of the value(s) inside the functor."
85	)]
86	#[document_parameters("The owned container.")]
87	impl<'a, Brand, A> AltDispatch<'a, Brand, A, Val> for Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
88	where
89		Brand: Alt,
90		A: 'a + Clone,
91	{
92		#[document_signature]
93		///
94		#[document_parameters("The other container to combine with.")]
95		///
96		#[document_returns("A new container from the combination of both inputs.")]
97		#[document_examples]
98		///
99		/// ```
100		/// use fp_library::{
101		/// 	brands::*,
102		/// 	functions::explicit::*,
103		/// };
104		///
105		/// let result = alt::<OptionBrand, _, _, _>(None, Some(5));
106		/// assert_eq!(result, Some(5));
107		/// ```
108		fn dispatch(
109			self,
110			other: Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
111		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
112			Brand::alt(self, other)
113		}
114	}
115
116	// -- Ref: borrowed container -> RefAlt::ref_alt --
117
118	/// Routes borrowed containers to [`RefAlt::ref_alt`].
119	#[document_type_parameters(
120		"The lifetime of the values.",
121		"The brand of the functor.",
122		"The type of the value(s) inside the functor."
123	)]
124	#[document_parameters("The borrowed container.")]
125	impl<'a, Brand, A> AltDispatch<'a, Brand, A, Ref> for &Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
126	where
127		Brand: RefAlt,
128		A: 'a + Clone,
129	{
130		#[document_signature]
131		///
132		#[document_parameters("The other borrowed container to combine with.")]
133		///
134		#[document_returns("A new container from the combination of both inputs.")]
135		#[document_examples]
136		///
137		/// ```
138		/// use fp_library::{
139		/// 	brands::*,
140		/// 	functions::explicit::*,
141		/// };
142		///
143		/// let x: Option<i32> = None;
144		/// let y = Some(5);
145		/// let result = alt::<OptionBrand, _, _, _>(&x, &y);
146		/// assert_eq!(result, Some(5));
147		/// ```
148		fn dispatch(
149			self,
150			other: &Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
151		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>) {
152			Brand::ref_alt(self, other)
153		}
154	}
155
156	// -- Inference wrapper --
157
158	/// Combines two values in a context, inferring the brand from the container type.
159	///
160	/// The `Brand` type parameter is inferred from the concrete type of `fa1`
161	/// via the `InferableBrand` trait. Both owned and borrowed containers are supported.
162	///
163	/// For types with multiple brands, use
164	/// [`explicit::alt`](crate::functions::explicit::alt) with a turbofish.
165	#[document_signature]
166	///
167	#[document_type_parameters(
168		"The lifetime of the values.",
169		"The container type (owned or borrowed). Brand is inferred from this.",
170		"The type of the value(s) inside the functor.",
171		"The brand, inferred via InferableBrand from FA and the element type."
172	)]
173	///
174	#[document_parameters(
175		"The first container (owned or borrowed).",
176		"The second container (same ownership as the first)."
177	)]
178	///
179	#[document_returns("A new container from the combination of both inputs.")]
180	#[document_examples]
181	///
182	/// ```
183	/// use fp_library::functions::*;
184	///
185	/// assert_eq!(alt(None, Some(5)), Some(5));
186	///
187	/// let x = vec![1, 2];
188	/// let y = vec![3, 4];
189	/// assert_eq!(alt(&x, &y), vec![1, 2, 3, 4]);
190	/// ```
191	pub fn alt<'a, FA, A: 'a + Clone, Brand>(
192		fa1: FA,
193		fa2: FA,
194	) -> <Brand as Kind_cdc7cd43dac7585f>::Of<'a, A>
195	where
196		Brand: Kind_cdc7cd43dac7585f,
197		FA: InferableBrand_cdc7cd43dac7585f<'a, Brand, A>
198			+ AltDispatch<'a, Brand, A, <FA as InferableBrand_cdc7cd43dac7585f<'a, Brand, A>>::Marker>, {
199		fa1.dispatch(fa2)
200	}
201
202	// -- Explicit dispatch free function --
203
204	/// Explicit dispatch functions requiring a Brand turbofish.
205	///
206	/// For most use cases, prefer the inference-enabled wrappers from
207	/// [`functions`](crate::functions).
208	pub mod explicit {
209		use super::*;
210
211		/// Combines two values in a context, choosing associatively.
212		///
213		/// Dispatches to either [`Alt::alt`] or [`RefAlt::ref_alt`]
214		/// based on whether the containers are owned or borrowed.
215		///
216		/// The `Marker` type parameter is inferred automatically by the
217		/// compiler from the container argument. Callers write
218		/// `alt::<Brand, _>(...)` and never need to specify `Marker` explicitly.
219		///
220		/// The dispatch is resolved at compile time with no runtime cost.
221		#[document_signature]
222		///
223		#[document_type_parameters(
224			"The lifetime of the values.",
225			"The brand of the functor.",
226			"The type of the value(s) inside the functor.",
227			"The container type (owned or borrowed), inferred from the argument.",
228			"Dispatch marker type, inferred automatically."
229		)]
230		///
231		#[document_parameters("The first container.", "The second container.")]
232		///
233		#[document_returns("A new container from the combination of both inputs.")]
234		///
235		#[document_examples]
236		///
237		/// ```
238		/// use fp_library::{
239		/// 	brands::*,
240		/// 	functions::explicit::*,
241		/// };
242		///
243		/// // Owned: dispatches to Alt::alt
244		/// let y = alt::<OptionBrand, _, _, _>(None, Some(5));
245		/// assert_eq!(y, Some(5));
246		///
247		/// // By-ref: dispatches to RefAlt::ref_alt
248		/// let x: Option<i32> = None;
249		/// let y = Some(5);
250		/// let z = alt::<OptionBrand, _, _, _>(&x, &y);
251		/// assert_eq!(z, Some(5));
252		/// ```
253		pub fn alt<'a, Brand: Kind_cdc7cd43dac7585f, A: 'a + Clone, FA, Marker>(
254			fa1: FA,
255			fa2: FA,
256		) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>)
257		where
258			FA: AltDispatch<'a, Brand, A, Marker>, {
259			fa1.dispatch(fa2)
260		}
261	}
262}
263
264pub use inner::*;
fp_library/dispatch/alt.rs

fp_library/dispatch/
alt.rs
