fp_library/dispatch/
apply_first.rs

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

fp_library/dispatch/
apply_first.rs
