fp_library/classes/
profunctor.rs

1//! Profunctors, which are functors contravariant in the first argument and covariant in the second.
2//!
3//! A profunctor represents a morphism between two categories, mapping objects and morphisms from one to the other.
4//!
5//! ### Examples
6//!
7//! ```
8//! use fp_library::{
9//! 	brands::*,
10//! 	functions::*,
11//! };
12//!
13//! // Function is a profunctor
14//! let f = |x: i32| x + 1;
15//! let g = dimap::<RcFnBrand, _, _, _, _>(
16//! 	|x: i32| x * 2,
17//! 	|x: i32| x - 1,
18//! 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
19//! );
20//! assert_eq!(g(10), 20); // (10 * 2) + 1 - 1 = 20
21//! ```
22
23pub use {
24	choice::*,
25	closed::*,
26	cochoice::*,
27	costrong::*,
28	strong::*,
29	wander::*,
30};
31
32pub mod choice;
33pub mod closed;
34pub mod cochoice;
35pub mod costrong;
36pub mod strong;
37pub mod wander;
38
39#[fp_macros::document_module]
40mod inner {
41	use {
42		crate::{
43			brands::*,
44			classes::*,
45			kinds::*,
46		},
47		fp_macros::*,
48	};
49
50	/// A type class for profunctors.
51	///
52	/// A profunctor is a type constructor that is contravariant in its first type parameter
53	/// and covariant in its second type parameter. This means it can pre-compose with a
54	/// function on the input and post-compose with a function on the output.
55	///
56	/// ### Hierarchy Unification
57	///
58	/// This trait is now the root of the unified profunctor and arrow hierarchies on
59	/// [`Kind_266801a817966495`]. This unification ensures that all profunctor-based abstractions
60	/// (including lenses and prisms) share a consistent higher-kinded representation with
61	/// strict lifetime bounds (`type Of<'a, T: 'a, U: 'a>: 'a;`).
62	///
63	/// By explicitly requiring that both type parameters outlive the application lifetime `'a`,
64	/// we provide the compiler with the necessary guarantees to handle trait objects
65	/// (like `dyn Fn`) commonly used in profunctor implementations. This resolves potential
66	/// E0310 errors where the compiler cannot otherwise prove that captured variables in
67	/// closures satisfy the required lifetime bounds.
68	///
69	/// ### Laws
70	///
71	/// `Profunctor` instances must satisfy the following laws:
72	/// * Identity: `dimap(identity, identity, p) = p`.
73	/// * Composition: `dimap(f1 ∘ f2, g2 ∘ g1, p) = dimap(f1, g1, dimap(f2, g2, p))`.
74	pub trait Profunctor: Kind_266801a817966495 {
75		/// Maps over both arguments of the profunctor.
76		///
77		/// This method applies a contravariant function to the first argument and a covariant
78		/// function to the second argument, transforming the profunctor.
79		#[document_signature]
80		///
81		#[document_type_parameters(
82			"The lifetime of the values.",
83			"The new input type (contravariant position).",
84			"The original input type.",
85			"The original output type.",
86			"The new output type (covariant position)."
87		)]
88		///
89		#[document_parameters(
90			"The contravariant function to apply to the input.",
91			"The covariant function to apply to the output.",
92			"The profunctor instance."
93		)]
94		///
95		#[document_returns("A new profunctor instance with transformed input and output types.")]
96		#[document_examples]
97		///
98		/// ```
99		/// use fp_library::{
100		/// 	brands::*,
101		/// 	classes::profunctor::*,
102		/// 	functions::*,
103		/// };
104		///
105		/// let f = |x: i32| x + 1;
106		/// let g = dimap::<RcFnBrand, _, _, _, _>(
107		/// 	|x: i32| x * 2,
108		/// 	|x: i32| x - 1,
109		/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
110		/// );
111		/// assert_eq!(g(10), 20); // (10 * 2) + 1 - 1 = 20
112		/// ```
113		fn dimap<'a, A: 'a, B: 'a, C: 'a, D: 'a>(
114			ab: impl Fn(A) -> B + 'a,
115			cd: impl Fn(C) -> D + 'a,
116			pbc: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, B, C>),
117		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, D>);
118
119		/// Maps contravariantly over the first argument.
120		///
121		/// This is a convenience method that maps only over the input (contravariant position).
122		#[document_signature]
123		///
124		#[document_type_parameters(
125			"The lifetime of the values.",
126			"The new input type.",
127			"The original input type.",
128			"The output type."
129		)]
130		///
131		#[document_parameters(
132			"The contravariant function to apply to the input.",
133			"The profunctor instance."
134		)]
135		///
136		#[document_returns("A new profunctor instance with transformed input type.")]
137		#[document_examples]
138		///
139		/// ```
140		/// use fp_library::{
141		/// 	brands::*,
142		/// 	classes::profunctor::*,
143		/// 	functions::*,
144		/// };
145		///
146		/// let f = |x: i32| x + 1;
147		/// let g = lmap::<RcFnBrand, _, _, _>(
148		/// 	|x: i32| x * 2,
149		/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
150		/// );
151		/// assert_eq!(g(10), 21); // (10 * 2) + 1 = 21
152		/// ```
153		fn lmap<'a, A: 'a, B: 'a, C: 'a>(
154			ab: impl Fn(A) -> B + 'a,
155			pbc: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, B, C>),
156		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, C>) {
157			Self::dimap(ab, crate::functions::identity, pbc)
158		}
159
160		/// Maps covariantly over the second argument.
161		///
162		/// This is a convenience method that maps only over the output (covariant position).
163		#[document_signature]
164		///
165		#[document_type_parameters(
166			"The lifetime of the values.",
167			"The input type.",
168			"The original output type.",
169			"The new output type."
170		)]
171		///
172		#[document_parameters(
173			"The covariant function to apply to the output.",
174			"The profunctor instance."
175		)]
176		///
177		#[document_returns("A new profunctor instance with transformed output type.")]
178		#[document_examples]
179		///
180		/// ```
181		/// use fp_library::{
182		/// 	brands::*,
183		/// 	classes::profunctor::*,
184		/// 	functions::*,
185		/// };
186		///
187		/// let f = |x: i32| x + 1;
188		/// let g = rmap::<RcFnBrand, _, _, _>(
189		/// 	|x: i32| x * 2,
190		/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
191		/// );
192		/// assert_eq!(g(10), 22); // (10 + 1) * 2 = 22
193		/// ```
194		fn rmap<'a, A: 'a, B: 'a, C: 'a>(
195			bc: impl Fn(B) -> C + 'a,
196			pab: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, B>),
197		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, C>) {
198			Self::dimap(crate::functions::identity, bc, pab)
199		}
200	}
201
202	/// Maps over both arguments of the profunctor.
203	///
204	/// Free function version that dispatches to [the type class' associated function][`Profunctor::dimap`].
205	#[document_signature]
206	///
207	#[document_type_parameters(
208		"The lifetime of the values.",
209		"The brand of the profunctor.",
210		"The new input type (contravariant position).",
211		"The original input type.",
212		"The original output type.",
213		"The new output type (covariant position)."
214	)]
215	///
216	#[document_parameters(
217		"The contravariant function to apply to the input.",
218		"The covariant function to apply to the output.",
219		"The profunctor instance."
220	)]
221	///
222	#[document_returns("A new profunctor instance with transformed input and output types.")]
223	#[document_examples]
224	///
225	/// ```
226	/// use fp_library::{
227	/// 	brands::*,
228	/// 	classes::profunctor::*,
229	/// 	functions::*,
230	/// };
231	///
232	/// let f = |x: i32| x + 1;
233	/// let g = dimap::<RcFnBrand, _, _, _, _>(
234	/// 	|x: i32| x * 2,
235	/// 	|x: i32| x - 1,
236	/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
237	/// );
238	/// assert_eq!(g(10), 20); // (10 * 2) + 1 - 1 = 20
239	/// ```
240	pub fn dimap<'a, Brand: Profunctor, A: 'a, B: 'a, C: 'a, D: 'a>(
241		ab: impl Fn(A) -> B + 'a,
242		cd: impl Fn(C) -> D + 'a,
243		pbc: Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, B, C>),
244	) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, D>) {
245		Brand::dimap(ab, cd, pbc)
246	}
247
248	/// Maps contravariantly over the first argument.
249	///
250	/// Free function version that dispatches to [the type class' associated function][`Profunctor::lmap`].
251	#[document_signature]
252	///
253	#[document_type_parameters(
254		"The lifetime of the values.",
255		"The brand of the profunctor.",
256		"The new input type.",
257		"The original input type.",
258		"The output type."
259	)]
260	///
261	#[document_parameters(
262		"The contravariant function to apply to the input.",
263		"The profunctor instance."
264	)]
265	///
266	#[document_returns("A new profunctor instance with transformed input type.")]
267	#[document_examples]
268	///
269	/// ```
270	/// use fp_library::{
271	/// 	brands::*,
272	/// 	classes::profunctor::*,
273	/// 	functions::*,
274	/// };
275	///
276	/// let f = |x: i32| x + 1;
277	/// let g = lmap::<RcFnBrand, _, _, _>(
278	/// 	|x: i32| x * 2,
279	/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
280	/// );
281	/// assert_eq!(g(10), 21); // (10 * 2) + 1 = 21
282	/// ```
283	pub fn lmap<'a, Brand: Profunctor, A: 'a, B: 'a, C: 'a>(
284		ab: impl Fn(A) -> B + 'a,
285		pbc: Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, B, C>),
286	) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, C>) {
287		Brand::lmap(ab, pbc)
288	}
289
290	/// Maps covariantly over the second argument.
291	///
292	/// Free function version that dispatches to [the type class' associated function][`Profunctor::rmap`].
293	#[document_signature]
294	///
295	#[document_type_parameters(
296		"The lifetime of the values.",
297		"The brand of the profunctor.",
298		"The input type.",
299		"The original output type.",
300		"The new output type."
301	)]
302	///
303	#[document_parameters(
304		"The covariant function to apply to the output.",
305		"The profunctor instance."
306	)]
307	///
308	#[document_returns("A new profunctor instance with transformed output type.")]
309	#[document_examples]
310	///
311	/// ```
312	/// use fp_library::{
313	/// 	brands::*,
314	/// 	classes::profunctor::*,
315	/// 	functions::*,
316	/// };
317	///
318	/// let f = |x: i32| x + 1;
319	/// let g = rmap::<RcFnBrand, _, _, _>(
320	/// 	|x: i32| x * 2,
321	/// 	std::rc::Rc::new(f) as std::rc::Rc<dyn Fn(i32) -> i32>,
322	/// );
323	/// assert_eq!(g(10), 22); // (10 + 1) * 2 = 22
324	/// ```
325	pub fn rmap<'a, Brand: Profunctor, A: 'a, B: 'a, C: 'a>(
326		bc: impl Fn(B) -> C + 'a,
327		pab: Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, B>),
328	) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, C>) {
329		Brand::rmap(bc, pab)
330	}
331
332	/// Lifts a pure function into a profunctor context.
333	///
334	/// Given a type that is both a [`Category`] (providing `identity`) and a
335	/// [`Profunctor`] (providing `rmap`), this function lifts a pure function
336	/// `A -> B` into the profunctor as `rmap(f, identity())`.
337	#[document_signature]
338	///
339	#[document_type_parameters(
340		"The lifetime of the function and its captured data.",
341		"The brand of the profunctor.",
342		"The input type.",
343		"The output type."
344	)]
345	///
346	#[document_parameters("The closure to lift.")]
347	///
348	#[document_returns("The lifted profunctor value.")]
349	#[document_examples]
350	///
351	/// ```
352	/// use fp_library::{
353	/// 	brands::*,
354	/// 	functions::*,
355	/// };
356	///
357	/// let f = arrow::<RcFnBrand, _, _>(|x: i32| x * 2);
358	/// assert_eq!(f(5), 10);
359	/// ```
360	pub fn arrow<'a, Brand, A, B: 'a>(
361		f: impl 'a + Fn(A) -> B
362	) -> Apply!(<Brand as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, A, B>)
363	where
364		Brand: Category + Profunctor, {
365		Brand::rmap(f, Brand::identity())
366	}
367
368	crate::impl_kind! {
369		impl<Brand: Profunctor, A: 'static> for ProfunctorFirstAppliedBrand<Brand, A> {
370			type Of<'a, B: 'a>: 'a = Apply!(<Brand as Kind!(type Of<'a, T: 'a, U: 'a>: 'a;)>::Of<'a, A, B>);
371		}
372	}
373
374	/// [`Functor`] instance for [`ProfunctorFirstAppliedBrand`].
375	///
376	/// Maps over the second (covariant) type parameter of a profunctor via [`Profunctor::rmap`].
377	#[document_type_parameters("The profunctor brand.", "The fixed first type parameter.")]
378	impl<Brand: Profunctor, A: 'static> Functor for ProfunctorFirstAppliedBrand<Brand, A> {
379		/// Map a function over the covariant type parameter.
380		#[document_signature]
381		#[document_type_parameters(
382			"The lifetime of the values.",
383			"The input type.",
384			"The output type."
385		)]
386		#[document_parameters("The function to apply.", "The profunctor value to map over.")]
387		#[document_returns("The mapped profunctor value.")]
388		#[document_examples]
389		///
390		/// ```
391		/// use fp_library::{
392		/// 	brands::*,
393		/// 	functions::*,
394		/// };
395		///
396		/// let f = std::rc::Rc::new(|x: i32| x + 1) as std::rc::Rc<dyn Fn(i32) -> i32>;
397		/// let g = map::<ProfunctorFirstAppliedBrand<RcFnBrand, i32>, _, _>(|x: i32| x * 2, f);
398		/// assert_eq!(g(5), 12); // (5 + 1) * 2
399		/// ```
400		fn map<'a, B: 'a, C: 'a>(
401			f: impl Fn(B) -> C + 'a,
402			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, B>),
403		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, C>) {
404			Brand::rmap(f, fa)
405		}
406	}
407
408	impl_kind! {
409		impl<Brand: Profunctor, B: 'static> for ProfunctorSecondAppliedBrand<Brand, B> {
410			type Of<'a, A: 'a>: 'a = Apply!(<Brand as Kind!(type Of<'a, T: 'a, U: 'a>: 'a;)>::Of<'a, A, B>);
411		}
412	}
413
414	/// [`Contravariant`] instance for [`ProfunctorSecondAppliedBrand`].
415	///
416	/// Contramaps over the first (contravariant) type parameter of a profunctor via [`Profunctor::lmap`].
417	#[document_type_parameters("The profunctor brand.", "The fixed second type parameter.")]
418	impl<Brand: Profunctor, B: 'static> Contravariant for ProfunctorSecondAppliedBrand<Brand, B> {
419		/// Contramap a function over the contravariant type parameter.
420		#[document_signature]
421		#[document_type_parameters(
422			"The lifetime of the values.",
423			"The input type.",
424			"The output type."
425		)]
426		#[document_parameters("The function to apply.", "The profunctor value to contramap over.")]
427		#[document_returns("The contramapped profunctor value.")]
428		#[document_examples]
429		///
430		/// ```
431		/// use fp_library::{
432		/// 	brands::*,
433		/// 	functions::*,
434		/// };
435		///
436		/// let f = std::rc::Rc::new(|x: i32| x + 1) as std::rc::Rc<dyn Fn(i32) -> i32>;
437		/// let g = contramap::<ProfunctorSecondAppliedBrand<RcFnBrand, i32>, _, _>(|x: i32| x * 2, f);
438		/// assert_eq!(g(5), 11); // (5 * 2) + 1
439		/// ```
440		fn contramap<'a, A: 'a, C: 'a>(
441			f: impl Fn(C) -> A + 'a,
442			fa: Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, A>),
443		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a>: 'a; )>::Of<'a, C>) {
444			Brand::lmap(f, fa)
445		}
446	}
447}
448
449pub use inner::*;
fp_library/classes/profunctor.rs

fp_library/classes/
profunctor.rs
