fp_library/classes/
optics.rs

1//! Traits for optics.
2
3pub mod fold;
4pub mod indexed_traversal;
5pub mod traversal;
6
7pub use {
8	fold::*,
9	indexed_traversal::*,
10	traversal::*,
11};
12
13#[fp_macros::document_module]
14mod inner {
15	use {
16		crate::{
17			brands::{
18				optics::*,
19				*,
20			},
21			classes::{
22				profunctor::*,
23				*,
24			},
25			kinds::*,
26		},
27		fp_macros::*,
28	};
29
30	/// A trait for optics that can be evaluated with any profunctor constraint.
31	///
32	/// This trait allows optics to be first-class values that can be composed
33	/// and stored while preserving their polymorphism over profunctor types.
34	#[document_type_parameters(
35		"The lifetime of the values.",
36		"The profunctor type.",
37		"The source type of the structure.",
38		"The target type of the structure after an update.",
39		"The source type of the focus.",
40		"The target type of the focus after an update."
41	)]
42	#[document_parameters("The optic instance.")]
43	pub trait Optic<'a, P: Profunctor, S: 'a, T: 'a, A: 'a, B: 'a> {
44		/// Evaluate the optic with a profunctor.
45		///
46		/// This method applies the optic transformation to a profunctor value.
47		#[document_signature]
48		///
49		#[document_parameters("The profunctor value to transform.")]
50		///
51		#[document_returns("The transformed profunctor value.")]
52		#[document_examples]
53		///
54		/// ```
55		/// use fp_library::{
56		/// 	brands::{
57		/// 		optics::*,
58		/// 		*,
59		/// 	},
60		/// 	classes::optics::*,
61		/// 	functions::*,
62		/// 	types::optics::*,
63		/// };
64		///
65		/// let l: LensPrime<RcBrand, (i32, String), i32> =
66		/// 	LensPrime::from_view_set(|(x, _)| x, |((_, s), x)| (x, s));
67		///
68		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
69		/// let modifier =
70		/// 	<LensPrime<RcBrand, (i32, String), i32> as Optic<RcFnBrand, _, _, _, _>>::evaluate(&l, f);
71		/// assert_eq!(modifier((21, "hello".to_string())), (42, "hello".to_string()));
72		/// ```
73		fn evaluate(
74			&self,
75			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
76		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
77	}
78
79	/// An isomorphism optic.
80	#[document_type_parameters(
81		"The lifetime of the values.",
82		"The source type of the structure.",
83		"The target type of the structure after an update.",
84		"The source type of the focus.",
85		"The target type of the focus after an update."
86	)]
87	#[document_parameters("The optic instance.")]
88	pub trait IsoOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
89		/// Evaluate the optic with any profunctor.
90		#[document_signature]
91		///
92		#[document_type_parameters("The profunctor type.")]
93		///
94		#[document_parameters("The profunctor value to transform.")]
95		///
96		#[document_returns("The transformed profunctor value.")]
97		#[document_examples]
98		///
99		/// ```
100		/// use fp_library::{
101		/// 	brands::{
102		/// 		optics::*,
103		/// 		*,
104		/// 	},
105		/// 	classes::optics::*,
106		/// 	functions::*,
107		/// 	types::optics::*,
108		/// };
109		///
110		/// let iso: IsoPrime<RcBrand, i32, i32> = IsoPrime::new(|x| x, |x| x);
111		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
112		/// let modifier = <IsoPrime<RcBrand, i32, i32> as IsoOptic<i32, i32, i32, i32>>::evaluate::<
113		/// 	RcFnBrand,
114		/// >(&iso, f);
115		/// assert_eq!(modifier(21), 42);
116		/// ```
117		fn evaluate<P: Profunctor + 'static>(
118			&self,
119			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
120		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
121	}
122
123	/// A lens optic.
124	#[document_type_parameters(
125		"The lifetime of the values.",
126		"The source type of the structure.",
127		"The target type of the structure after an update.",
128		"The source type of the focus.",
129		"The target type of the focus after an update."
130	)]
131	#[document_parameters("The optic instance.")]
132	pub trait LensOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
133		/// Evaluate the optic with a strong profunctor.
134		#[document_signature]
135		///
136		#[document_type_parameters("The profunctor type.")]
137		///
138		#[document_parameters("The profunctor value to transform.")]
139		///
140		#[document_returns("The transformed profunctor value.")]
141		#[document_examples]
142		///
143		/// ```
144		/// use fp_library::{
145		/// 	brands::{
146		/// 		optics::*,
147		/// 		*,
148		/// 	},
149		/// 	classes::optics::*,
150		/// 	functions::*,
151		/// 	types::optics::*,
152		/// };
153		///
154		/// let l: LensPrime<RcBrand, (i32, String), i32> =
155		/// 	LensPrime::from_view_set(|(x, _)| x, |((_, s), x)| (x, s));
156		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
157		/// let modifier = <LensPrime<RcBrand, (i32, String), i32> as LensOptic<
158		/// 	(i32, String),
159		/// 	(i32, String),
160		/// 	i32,
161		/// 	i32,
162		/// >>::evaluate::<RcFnBrand>(&l, f);
163		/// assert_eq!(modifier((21, "hi".to_string())), (42, "hi".to_string()));
164		/// ```
165		fn evaluate<P: Strong>(
166			&self,
167			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
168		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
169	}
170
171	/// A prism optic.
172	#[document_type_parameters(
173		"The lifetime of the values.",
174		"The source type of the structure.",
175		"The target type of the structure after an update.",
176		"The source type of the focus.",
177		"The target type of the focus after an update."
178	)]
179	#[document_parameters("The optic instance.")]
180	pub trait PrismOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
181		/// Evaluate the optic with a choice profunctor.
182		#[document_signature]
183		///
184		#[document_type_parameters("The profunctor type.")]
185		///
186		#[document_parameters("The profunctor value to transform.")]
187		///
188		#[document_returns("The transformed profunctor value.")]
189		#[document_examples]
190		///
191		/// ```
192		/// use fp_library::{
193		/// 	brands::{
194		/// 		optics::*,
195		/// 		*,
196		/// 	},
197		/// 	classes::optics::*,
198		/// 	functions::*,
199		/// 	types::optics::*,
200		/// };
201		///
202		/// let p: PrismPrime<RcBrand, Option<i32>, i32> = PrismPrime::from_option(|o| o, Some);
203		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
204		/// let modifier = <PrismPrime<RcBrand, Option<i32>, i32> as PrismOptic<
205		/// 	Option<i32>,
206		/// 	Option<i32>,
207		/// 	i32,
208		/// 	i32,
209		/// >>::evaluate::<RcFnBrand>(&p, f);
210		/// assert_eq!(modifier(Some(21)), Some(42));
211		/// ```
212		fn evaluate<P: Choice>(
213			&self,
214			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
215		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
216	}
217
218	/// An affine traversal optic.
219	#[document_type_parameters(
220		"The lifetime of the values.",
221		"The source type of the structure.",
222		"The target type of the structure after an update.",
223		"The source type of the focus.",
224		"The target type of the focus after an update."
225	)]
226	#[document_parameters("The optic instance.")]
227	pub trait AffineTraversalOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
228		/// Evaluate the optic with a strong and choice profunctor.
229		#[document_signature]
230		///
231		#[document_type_parameters("The profunctor type.")]
232		///
233		#[document_parameters("The profunctor value to transform.")]
234		///
235		#[document_returns("The transformed profunctor value.")]
236		#[document_examples]
237		///
238		/// ```
239		/// use fp_library::{
240		/// 	brands::{
241		/// 		optics::*,
242		/// 		*,
243		/// 	},
244		/// 	classes::optics::*,
245		/// 	functions::*,
246		/// 	types::optics::*,
247		/// };
248		///
249		/// let at: AffineTraversalPrime<RcBrand, (i32, String), i32> =
250		/// 	AffineTraversalPrime::from_preview_set(|(x, _)| Some(x), |((_, s), x)| (x, s));
251		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
252		/// let modifier = <AffineTraversalPrime<RcBrand, (i32, String), i32> as AffineTraversalOptic<
253		/// 	(i32, String),
254		/// 	(i32, String),
255		/// 	i32,
256		/// 	i32,
257		/// >>::evaluate::<RcFnBrand>(&at, f);
258		/// assert_eq!(modifier((21, "hi".to_string())), (42, "hi".to_string()));
259		/// ```
260		fn evaluate<P: Strong + Choice>(
261			&self,
262			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
263		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
264	}
265
266	/// A traversal optic.
267	#[document_type_parameters(
268		"The lifetime of the values.",
269		"The source type of the structure.",
270		"The target type of the structure after an update.",
271		"The source type of the focus.",
272		"The target type of the focus after an update."
273	)]
274	#[document_parameters("The optic instance.")]
275	pub trait TraversalOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
276		/// Evaluate the optic with a wander profunctor.
277		#[document_signature]
278		///
279		#[document_type_parameters("The profunctor type.")]
280		///
281		#[document_parameters("The profunctor value to transform.")]
282		///
283		#[document_returns("The transformed profunctor value.")]
284		#[document_examples]
285		///
286		/// ```
287		/// use fp_library::{
288		/// 	brands::{
289		/// 		optics::*,
290		/// 		*,
291		/// 	},
292		/// 	classes::optics::*,
293		/// 	functions::*,
294		/// 	types::optics::*,
295		/// };
296		///
297		/// // Use Vec's built-in optic support
298		/// let v = vec![1, 2, 3];
299		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
300		/// let result = f(v[0]); // Simple example showing the concept
301		/// assert_eq!(result, 2);
302		/// ```
303		fn evaluate<P: Wander>(
304			&self,
305			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
306		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
307	}
308
309	/// A getter optic.
310	#[document_type_parameters(
311		"The lifetime of the values.",
312		"The source type of the structure.",
313		"The focus type."
314	)]
315	#[document_parameters("The optic instance.")]
316	pub trait GetterOptic<'a, S: 'a, A: 'a> {
317		/// Evaluate the optic with the forget profunctor.
318		#[document_signature]
319		///
320		#[document_type_parameters(
321			"The return type of the forget profunctor.",
322			"The reference-counted pointer type."
323		)]
324		///
325		#[document_parameters("The profunctor value to transform.")]
326		///
327		#[document_returns("The transformed forget profunctor value.")]
328		#[document_examples]
329		///
330		/// ```
331		/// use fp_library::{
332		/// 	brands::{
333		/// 		optics::*,
334		/// 		*,
335		/// 	},
336		/// 	classes::optics::*,
337		/// 	functions::*,
338		/// 	types::optics::*,
339		/// };
340		///
341		/// let g: GetterPrime<RcBrand, (i32, String), i32> = GetterPrime::new(|(x, _)| x);
342		/// let f = Forget::<RcBrand, i32, i32, i32>::new(|x| x);
343		/// let folded =
344		/// 	<GetterPrime<RcBrand, (i32, String), i32> as GetterOptic<(i32, String), i32>>::evaluate::<
345		/// 		i32,
346		/// 		RcBrand,
347		/// 	>(&g, f);
348		/// assert_eq!(folded.run((42, "hi".to_string())), 42);
349		/// ```
350		fn evaluate<R: 'a + 'static, PointerBrand: ToDynCloneFn + 'static>(
351			&self,
352			pab: Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, A>),
353		) -> Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, S>);
354	}
355
356	/// A fold optic.
357	#[document_type_parameters(
358		"The lifetime of the values.",
359		"The source type of the structure.",
360		"The focus type."
361	)]
362	#[document_parameters("The optic instance.")]
363	pub trait FoldOptic<'a, S: 'a, A: 'a> {
364		/// Evaluate the optic with the forget profunctor for any monoid.
365		#[document_signature]
366		///
367		#[document_type_parameters("The monoid type.", "The reference-counted pointer type.")]
368		///
369		#[document_parameters("The profunctor value to transform.")]
370		///
371		#[document_returns("The transformed forget profunctor value.")]
372		///
373		/// ### `R: Clone` Requirement
374		///
375		/// The result monoid `R` must implement [`Clone`] because the fold is internally implemented
376		/// via [`Wander`] with the [`Forget`](crate::types::optics::Forget) profunctor, which stores
377		/// `R` inside [`Const`](crate::types::const_val::Const). The traversal applies
378		/// [`TraversalFunc::apply`] with
379		/// [`ConstBrand<R>`](crate::brands::ConstBrand) as the applicative, and that
380		/// requires `Const<R, B>: Clone`, which in turn requires `R: Clone`.
381		#[document_examples]
382		///
383		/// ```
384		/// use fp_library::{
385		/// 	brands::{
386		/// 		optics::*,
387		/// 		*,
388		/// 	},
389		/// 	classes::{
390		/// 		Monoid,
391		/// 		optics::*,
392		/// 	},
393		/// 	functions::*,
394		/// 	types::optics::*,
395		/// };
396		/// let f_optic: FoldPrime<RcBrand, Vec<i32>, i32, _> =
397		/// 	FoldPrime::new(IterableFoldFn(|v: Vec<i32>| v));
398		/// let f = Forget::<RcBrand, String, i32, i32>::new(|x| x.to_string());
399		/// let folded = <FoldPrime<RcBrand, Vec<i32>, i32, _> as FoldOptic<Vec<i32>, i32>>::evaluate::<
400		/// 	String,
401		/// 	RcBrand,
402		/// >(&f_optic, f);
403		/// assert_eq!(folded.run(vec![1, 2, 3]), "123".to_string());
404		/// ```
405		fn evaluate<R: 'a + Monoid + Clone + 'static, PointerBrand: ToDynCloneFn + 'static>(
406			&self,
407			pab: Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, A>),
408		) -> Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, S>);
409	}
410
411	/// A setter optic.
412	#[document_type_parameters(
413		"The lifetime of the values.",
414		"The reference-counted pointer type.",
415		"The source type of the structure.",
416		"The target type of the structure after an update.",
417		"The source type of the focus.",
418		"The target type of the focus after an update."
419	)]
420	#[document_parameters("The optic instance.")]
421	pub trait SetterOptic<'a, PointerBrand: ToDynCloneFn, S: 'a, T: 'a, A: 'a, B: 'a> {
422		/// Evaluate the optic with the function profunctor.
423		#[document_signature]
424		///
425		#[document_parameters("The profunctor value to transform.")]
426		///
427		#[document_returns("The transformed function profunctor value.")]
428		#[document_examples]
429		///
430		/// ```
431		/// use fp_library::{
432		/// 	brands::{
433		/// 		optics::*,
434		/// 		*,
435		/// 	},
436		/// 	classes::optics::*,
437		/// 	functions::*,
438		/// 	types::optics::*,
439		/// };
440		///
441		/// let s: SetterPrime<RcBrand, (i32, String), i32> =
442		/// 	SetterPrime::new(|(s, f): ((i32, String), Box<dyn Fn(i32) -> i32>)| (f(s.0), s.1));
443		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
444		/// let modifier = <SetterPrime<RcBrand, (i32, String), i32> as SetterOptic<
445		/// 	RcBrand,
446		/// 	(i32, String),
447		/// 	(i32, String),
448		/// 	i32,
449		/// 	i32,
450		/// >>::evaluate(&s, f);
451		/// assert_eq!(modifier((21, "hi".to_string())), (42, "hi".to_string()));
452		/// ```
453		fn evaluate(
454			&self,
455			pab: Apply!(<FnBrand<PointerBrand> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
456		) -> Apply!(<FnBrand<PointerBrand> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
457	}
458
459	/// An indexed lens optic.
460	#[document_type_parameters(
461		"The lifetime of the values.",
462		"The index type.",
463		"The source type of the structure.",
464		"The target type of the structure after an update.",
465		"The source type of the focus.",
466		"The target type of the focus after an update."
467	)]
468	#[document_parameters("The optic instance.")]
469	pub trait IndexedLensOptic<'a, I: 'a, S: 'a, T: 'a, A: 'a, B: 'a> {
470		/// Evaluate the optic with a strong profunctor.
471		#[document_signature]
472		///
473		#[document_type_parameters("The profunctor type.")]
474		///
475		#[document_parameters("The indexed profunctor value to transform.")]
476		///
477		#[document_returns("The transformed profunctor value.")]
478		#[document_examples]
479		///
480		/// ```
481		/// use fp_library::{
482		/// 	brands::{
483		/// 		optics::*,
484		/// 		*,
485		/// 	},
486		/// 	classes::optics::*,
487		/// 	functions::*,
488		/// 	types::optics::*,
489		/// };
490		///
491		/// let l: LensPrime<RcBrand, (i32, String), i32> =
492		/// 	LensPrime::from_view_set(|(x, _)| x, |((_, s), x)| (x, s));
493		/// assert_eq!(l.over((21, "hi".to_string()), |x| x * 2), (42, "hi".to_string()));
494		/// ```
495		fn evaluate<P: Strong>(
496			&self,
497			pab: crate::types::optics::Indexed<'a, P, I, A, B>,
498		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
499	}
500
501	/// An indexed traversal optic.
502	#[document_type_parameters(
503		"The lifetime of the values.",
504		"The index type.",
505		"The source type of the structure.",
506		"The target type of the structure after an update.",
507		"The source type of the focus.",
508		"The target type of the focus after an update."
509	)]
510	#[document_parameters("The optic instance.")]
511	pub trait IndexedTraversalOptic<'a, I: 'a, S: 'a, T: 'a, A: 'a, B: 'a> {
512		/// Evaluate the optic with a wander profunctor.
513		#[document_signature]
514		///
515		#[document_type_parameters("The profunctor type.")]
516		///
517		#[document_parameters("The indexed profunctor value to transform.")]
518		///
519		#[document_returns("The transformed profunctor value.")]
520		#[document_examples]
521		///
522		/// ```
523		/// use fp_library::{
524		/// 	brands::{
525		/// 		optics::*,
526		/// 		*,
527		/// 	},
528		/// 	classes::optics::*,
529		/// 	functions::*,
530		/// 	types::optics::*,
531		/// };
532		///
533		/// let v = vec![1, 2, 3];
534		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
535		/// assert_eq!(f(v[0]), 2);
536		/// ```
537		fn evaluate<P: Wander>(
538			&self,
539			pab: crate::types::optics::Indexed<'a, P, I, A, B>,
540		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
541	}
542
543	/// An indexed getter optic.
544	#[document_type_parameters(
545		"The lifetime of the values.",
546		"The index type.",
547		"The source type of the structure.",
548		"The focus type."
549	)]
550	#[document_parameters("The optic instance.")]
551	pub trait IndexedGetterOptic<'a, I: 'a, S: 'a, A: 'a> {
552		/// Evaluate the optic with the forget profunctor.
553		#[document_signature]
554		///
555		#[document_type_parameters(
556			"The return type of the forget profunctor.",
557			"The reference-counted pointer type."
558		)]
559		///
560		#[document_parameters("The indexed profunctor value to transform.")]
561		///
562		#[document_returns("The transformed forget profunctor value.")]
563		#[document_examples]
564		///
565		/// ```
566		/// use fp_library::{
567		/// 	brands::{
568		/// 		optics::*,
569		/// 		*,
570		/// 	},
571		/// 	classes::optics::*,
572		/// 	functions::*,
573		/// 	types::optics::*,
574		/// };
575		///
576		/// let g: GetterPrime<RcBrand, (i32, String), i32> = GetterPrime::new(|(x, _)| x);
577		/// let f = Forget::<RcBrand, i32, i32, i32>::new(|x| x);
578		/// let folded =
579		/// 	<GetterPrime<RcBrand, (i32, String), i32> as GetterOptic<(i32, String), i32>>::evaluate::<
580		/// 		i32,
581		/// 		RcBrand,
582		/// 	>(&g, f);
583		/// assert_eq!(folded.run((42, "hi".to_string())), 42);
584		/// ```
585		fn evaluate<R: 'a + 'static, PointerBrand: ToDynCloneFn + 'static>(
586			&self,
587			pab: crate::types::optics::Indexed<'a, ForgetBrand<PointerBrand, R>, I, A, A>,
588		) -> Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, S>);
589	}
590
591	/// An indexed fold optic.
592	#[document_type_parameters(
593		"The lifetime of the values.",
594		"The index type.",
595		"The source type of the structure.",
596		"The focus type."
597	)]
598	#[document_parameters("The optic instance.")]
599	pub trait IndexedFoldOptic<'a, I: 'a, S: 'a, A: 'a> {
600		/// Evaluate the optic with the forget profunctor for any monoid.
601		#[document_signature]
602		///
603		#[document_type_parameters("The monoid type.", "The reference-counted pointer type.")]
604		///
605		#[document_parameters("The indexed profunctor value to transform.")]
606		///
607		#[document_returns("The transformed forget profunctor value.")]
608		#[document_examples]
609		///
610		/// ```
611		/// use fp_library::{
612		/// 	brands::{
613		/// 		optics::*,
614		/// 		*,
615		/// 	},
616		/// 	classes::{
617		/// 		Monoid,
618		/// 		optics::*,
619		/// 	},
620		/// 	functions::*,
621		/// 	types::optics::*,
622		/// };
623		/// let f_optic: FoldPrime<RcBrand, Vec<i32>, i32, _> =
624		/// 	FoldPrime::new(IterableFoldFn(|v: Vec<i32>| v));
625		/// let f = Forget::<RcBrand, String, i32, i32>::new(|x| x.to_string());
626		/// let folded = <FoldPrime<RcBrand, Vec<i32>, i32, _> as FoldOptic<Vec<i32>, i32>>::evaluate::<
627		/// 	String,
628		/// 	RcBrand,
629		/// >(&f_optic, f);
630		/// assert_eq!(folded.run(vec![1, 2, 3]), "123".to_string());
631		/// ```
632		///
633		/// ### `R: Clone` Requirement
634		///
635		/// The result monoid `R` must implement [`Clone`] because the fold is internally implemented
636		/// via [`Wander`] with the [`Forget`](crate::types::optics::Forget) profunctor, which stores
637		/// `R` inside [`Const`](crate::types::const_val::Const). The traversal applies
638		/// [`IndexedTraversalFunc::apply`](crate::classes::optics::IndexedTraversalFunc::apply) with
639		/// [`ConstBrand<R>`](crate::brands::ConstBrand) as the applicative, and that
640		/// requires `Const<R, B>: Clone`, which in turn requires `R: Clone`.
641		fn evaluate<R: 'a + Monoid + Clone + 'static, PointerBrand: ToDynCloneFn + 'static>(
642			&self,
643			pab: crate::types::optics::Indexed<'a, ForgetBrand<PointerBrand, R>, I, A, A>,
644		) -> Apply!(<ForgetBrand<PointerBrand, R> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, S>);
645	}
646
647	/// An indexed setter optic.
648	#[document_type_parameters(
649		"The lifetime of the values.",
650		"The reference-counted pointer type.",
651		"The index type.",
652		"The source type of the structure.",
653		"The target type of the structure after an update.",
654		"The source type of the focus.",
655		"The target type of the focus after an update."
656	)]
657	#[document_parameters("The optic instance.")]
658	pub trait IndexedSetterOptic<'a, PointerBrand: ToDynCloneFn, I: 'a, S: 'a, T: 'a, A: 'a, B: 'a>
659	{
660		/// Evaluate the optic with the function profunctor.
661		#[document_signature]
662		///
663		#[document_parameters("The indexed profunctor value to transform.")]
664		///
665		#[document_returns("The transformed function profunctor value.")]
666		#[document_examples]
667		///
668		/// ```
669		/// use fp_library::{
670		/// 	brands::{
671		/// 		optics::*,
672		/// 		*,
673		/// 	},
674		/// 	classes::optics::*,
675		/// 	functions::*,
676		/// 	types::optics::*,
677		/// };
678		///
679		/// let s: SetterPrime<RcBrand, (i32, String), i32> =
680		/// 	SetterPrime::new(|(s, f): ((i32, String), Box<dyn Fn(i32) -> i32>)| (f(s.0), s.1));
681		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
682		/// let modifier = <SetterPrime<RcBrand, (i32, String), i32> as SetterOptic<
683		/// 	RcBrand,
684		/// 	(i32, String),
685		/// 	(i32, String),
686		/// 	i32,
687		/// 	i32,
688		/// >>::evaluate(&s, f);
689		/// assert_eq!(modifier((21, "hi".to_string())), (42, "hi".to_string()));
690		/// ```
691		fn evaluate(
692			&self,
693			pab: crate::types::optics::Indexed<'a, FnBrand<PointerBrand>, I, A, B>,
694		) -> Apply!(<FnBrand<PointerBrand> as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
695	}
696
697	/// A grate optic.
698	#[document_type_parameters(
699		"The lifetime of the values.",
700		"The cloneable function brand used by the profunctor's `Closed` instance.",
701		"The source type of the structure.",
702		"The target type of the structure after an update.",
703		"The source type of the focus.",
704		"The target type of the focus after an update."
705	)]
706	#[document_parameters("The optic instance.")]
707	pub trait GrateOptic<'a, FunctionBrand: LiftFn, S: 'a, T: 'a, A: 'a, B: 'a> {
708		/// Evaluate the optic with a closed profunctor.
709		#[document_signature]
710		///
711		#[document_type_parameters("The profunctor type.")]
712		///
713		#[document_parameters("The profunctor value to transform.")]
714		///
715		#[document_returns("The transformed profunctor value.")]
716		#[document_examples]
717		///
718		/// ```
719		/// use fp_library::{
720		/// 	brands::{
721		/// 		optics::*,
722		/// 		*,
723		/// 	},
724		/// 	classes::optics::*,
725		/// 	functions::*,
726		/// 	types::optics::*,
727		/// };
728		///
729		/// // Simple example showing the grate concept
730		/// let pair = (21, 10);
731		/// let f = lift_fn_new::<RcFnBrand, _, _>(|x: i32| x * 2);
732		/// assert_eq!(f(pair.0), 42);
733		/// assert_eq!(f(pair.1), 20);
734		/// ```
735		fn evaluate<P: Closed<FunctionBrand>>(
736			&self,
737			pab: Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
738		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
739	}
740
741	/// A review optic.
742	#[document_type_parameters(
743		"The lifetime of the values.",
744		"The source type of the structure.",
745		"The target type of the structure after an update.",
746		"The source type of the focus.",
747		"The target type of the focus after an update."
748	)]
749	#[document_parameters("The optic instance.")]
750	pub trait ReviewOptic<'a, S: 'a, T: 'a, A: 'a, B: 'a> {
751		/// Evaluate the optic with the tagged profunctor.
752		#[document_signature]
753		///
754		#[document_parameters("The profunctor value to transform.")]
755		///
756		#[document_returns("The transformed tagged profunctor value.")]
757		#[document_examples]
758		///
759		/// ```
760		/// use fp_library::{
761		/// 	brands::{
762		/// 		optics::*,
763		/// 		*,
764		/// 	},
765		/// 	classes::optics::*,
766		/// 	functions::*,
767		/// 	types::optics::*,
768		/// };
769		///
770		/// let r: PrismPrime<RcBrand, Option<i32>, i32> = PrismPrime::from_option(|o| o, Some);
771		/// let f = Tagged::new(21);
772		/// let reviewed = <PrismPrime<RcBrand, Option<i32>, i32> as ReviewOptic<
773		/// 	Option<i32>,
774		/// 	Option<i32>,
775		/// 	i32,
776		/// 	i32,
777		/// >>::evaluate(&r, f);
778		/// assert_eq!(reviewed.0, Some(21));
779		/// ```
780		fn evaluate(
781			&self,
782			pab: Apply!(<TaggedBrand as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, A, B>),
783		) -> Apply!(<TaggedBrand as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
784	}
785
786	/// Helper trait for `optics_un_index`.
787	#[document_type_parameters(
788		"The lifetime of the values.",
789		"The profunctor type.",
790		"The index type.",
791		"The source type of the structure.",
792		"The target type of the structure.",
793		"The source type of the focus.",
794		"The target type of the focus."
795	)]
796	#[document_parameters("The adapter instance.")]
797	pub trait IndexedOpticAdapter<'a, P: Profunctor, I, S, T, A, B> {
798		/// Evaluate the optic with an indexed profunctor.
799		#[document_signature]
800		///
801		#[document_parameters("The indexed profunctor value.")]
802		///
803		#[document_returns("The transformed profunctor value.")]
804		#[document_examples]
805		///
806		/// ```
807		/// use fp_library::{
808		/// 	brands::{
809		/// 		optics::*,
810		/// 		*,
811		/// 	},
812		/// 	classes::optics::*,
813		/// 	functions::*,
814		/// 	types::optics::*,
815		/// };
816		///
817		/// let l: LensPrime<RcBrand, (i32, String), i32> =
818		/// 	LensPrime::from_view_set(|(x, _)| x, |((_, s), x)| (x, s));
819		/// assert_eq!(l.over((21, "hi".to_string()), |x| x * 2), (42, "hi".to_string()));
820		/// ```
821		fn evaluate_indexed(
822			&self,
823			pab: crate::types::optics::Indexed<'a, P, I, A, B>,
824		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
825	}
826
827	/// Helper trait for `optics_as_index`.
828	#[document_type_parameters(
829		"The lifetime of the values.",
830		"The profunctor type.",
831		"The index type.",
832		"The source type of the structure.",
833		"The target type of the structure.",
834		"The source type of the focus.",
835		"The target type of the focus."
836	)]
837	#[document_parameters("The adapter instance.")]
838	pub trait IndexedOpticAdapterDiscardsFocus<'a, P: Profunctor, I, S, T, A, B> {
839		/// Evaluate the optic with an indexed profunctor, discarding the focus.
840		#[document_signature]
841		///
842		#[document_parameters("The indexed profunctor value.")]
843		///
844		#[document_returns("The transformed profunctor value.")]
845		#[document_examples]
846		///
847		/// ```
848		/// use fp_library::{
849		/// 	brands::{
850		/// 		optics::*,
851		/// 		*,
852		/// 	},
853		/// 	classes::optics::*,
854		/// 	functions::*,
855		/// 	types::optics::*,
856		/// };
857		///
858		/// let l: LensPrime<RcBrand, (i32, String), i32> =
859		/// 	LensPrime::from_view_set(|(x, _)| x, |((_, s), x)| (x, s));
860		/// assert_eq!(l.over((21, "hi".to_string()), |x| x * 2), (42, "hi".to_string()));
861		/// ```
862		fn evaluate_indexed_discards_focus(
863			&self,
864			pab: crate::types::optics::Indexed<'a, P, I, A, B>,
865		) -> Apply!(<P as Kind!( type Of<'b, T: 'b, U: 'b>: 'b; )>::Of<'a, S, T>);
866	}
867}
868
869pub use inner::*;
fp_library/classes/optics.rs

fp_library/classes/
optics.rs
