fp_library/types/optics/

stall.rs

//! The `Stall` profunctor, used for affine traversals.
//!
//! `Stall<A, B, S, T>` wraps a preview function `S -> Result<A, T>` and a setter function `S -> B -> T`.

#[fp_macros::document_module]
mod inner {
	use {
		crate::{
			Apply,
			brands::optics::*,
			classes::{
				profunctor::{
					Choice,
					Profunctor,
					Strong,
				},
				*,
			},
			impl_kind,
			kinds::*,
		},
		fp_macros::*,
	};

	/// The `Stall` profunctor.
	#[document_type_parameters(
		"The lifetime of the functions.",
		"The cloneable function brand.",
		"The type of the value produced by the preview function.",
		"The type of the value consumed by the setter.",
		"The source type of the structure.",
		"The target type of the structure."
	)]
	pub struct Stall<'a, FunctionBrand: LiftFn, A: 'a, B: 'a, S: 'a, T: 'a> {
		/// Preview function: tries to extract the focus.
		pub get: <FunctionBrand as CloneFn>::Of<'a, S, Result<A, T>>,
		/// Setter function.
		pub set: <FunctionBrand as CloneFn>::Of<'a, (S, B), T>,
	}

	#[document_type_parameters(
		"The lifetime of the functions.",
		"The cloneable function brand.",
		"The type of the value produced by the preview function.",
		"The type of the value consumed by the setter.",
		"The source type of the structure.",
		"The target type of the structure."
	)]
	impl<'a, FunctionBrand: LiftFn, A: 'a, B: 'a, S: 'a, T: 'a> Stall<'a, FunctionBrand, A, B, S, T> {
		/// Creates a new `Stall` instance.
		#[document_signature]
		///
		#[document_parameters("The preview function.", "The setter function.")]
		///
		#[document_returns("A new instance of the type.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::RcFnBrand,
		/// 	classes::clone_fn::new as lift_fn_new,
		/// 	types::optics::Stall,
		/// };
		///
		/// let stall = Stall::<RcFnBrand, i32, i32, (i32, i32), (i32, i32)>::new(
		/// 	lift_fn_new::<RcFnBrand, _, _>(|s: (i32, i32)| Ok(s.0)),
		/// 	lift_fn_new::<RcFnBrand, _, _>(|(s, b): ((i32, i32), i32)| (b, s.1)),
		/// );
		/// assert_eq!((stall.get)((10, 20)), Ok(10));
		/// assert_eq!((stall.set)(((10, 20), 30)), (30, 20));
		/// ```
		pub fn new(
			get: <FunctionBrand as CloneFn>::Of<'a, S, Result<A, T>>,
			set: <FunctionBrand as CloneFn>::Of<'a, (S, B), T>,
		) -> Self {
			Stall {
				get,
				set,
			}
		}
	}

	impl_kind! {
		impl<FunctionBrand: LiftFn + 'static, A: 'static, B: 'static> for StallBrand<FunctionBrand, A, B> {
			#[document_default]
			type Of<'a, S: 'a, T: 'a>: 'a = Stall<'a, FunctionBrand, A, B, S, T>;
		}
	}

	#[document_type_parameters(
		"The cloneable function brand.",
		"The type of the value produced by the preview function.",
		"The type of the value consumed by the setter."
	)]
	impl<FunctionBrand: LiftFn + 'static, A: 'static, B: 'static> Profunctor
		for StallBrand<FunctionBrand, A, B>
	{
		/// Maps functions over the input and output of the `Stall` profunctor.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the functions.",
			"The source type of the new structure.",
			"The target type of the new structure.",
			"The source type of the original structure.",
			"The target type of the original structure."
		)]
		///
		#[document_parameters(
			"The function to apply to the input.",
			"The function to apply to the output.",
			"The stall instance to transform."
		)]
		#[document_returns("A transformed `Stall` instance.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		optics::*,
		/// 		*,
		/// 	},
		/// 	classes::{
		/// 		clone_fn::new as lift_fn_new,
		/// 		optics::*,
		/// 		profunctor::*,
		/// 	},
		/// 	types::optics::*,
		/// };
		///
		/// // Stall is usually used internally by AffineTraversal optics
		/// let stall = Stall::<RcFnBrand, i32, i32, (i32, i32), (i32, i32)>::new(
		/// 	lift_fn_new::<RcFnBrand, _, _>(|s: (i32, i32)| Ok(s.0)),
		/// 	lift_fn_new::<RcFnBrand, _, _>(|(s, b): ((i32, i32), i32)| (b, s.1)),
		/// );
		/// let transformed = <StallBrand<RcFnBrand, i32, i32> as Profunctor>::dimap(
		/// 	|s: (i32, i32)| s,
		/// 	|t: (i32, i32)| t,
		/// 	stall,
		/// );
		/// assert_eq!((transformed.get)((10, 20)), Ok(10));
		/// ```
		fn dimap<'a, S: 'a, T: 'a, U: 'a, V: 'a>(
			st: impl Fn(S) -> T + 'a,
			uv: impl Fn(U) -> V + 'a,
			puv: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, T, U>),
		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, S, V>) {
			let get = puv.get;
			let set = puv.set;
			let st = <FunctionBrand as LiftFn>::new(st);
			let uv = <FunctionBrand as LiftFn>::new(uv);
			let st_2 = st.clone();
			let uv_2 = uv.clone();
			Stall::new(
				<FunctionBrand as LiftFn>::new(move |s: S| (*get)((*st)(s)).map_err(|u| (*uv)(u))),
				<FunctionBrand as LiftFn>::new(move |(s, b): (S, B)| {
					(*uv_2)((*set)(((*st_2)(s), b)))
				}),
			)
		}
	}

	#[document_type_parameters(
		"The cloneable function brand.",
		"The type of the value produced by the preview function.",
		"The type of the value consumed by the setter."
	)]
	impl<FunctionBrand: LiftFn + 'static, A: 'static, B: 'static> Strong
		for StallBrand<FunctionBrand, A, B>
	{
		/// Lifts the `Stall` profunctor to operate on the first component of a tuple.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the functions.",
			"The source type of the structure.",
			"The target type of the structure.",
			"The type of the other component."
		)]
		///
		#[document_parameters("The stall instance to transform.")]
		#[document_returns("A transformed `Stall` instance that operates on tuples.")]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		optics::*,
		/// 		*,
		/// 	},
		/// 	classes::{
		/// 		clone_fn::new as lift_fn_new,
		/// 		optics::*,
		/// 		profunctor::*,
		/// 	},
		/// 	types::optics::*,
		/// };
		///
		/// let stall = Stall::<RcFnBrand, i32, i32, i32, i32>::new(
		/// 	lift_fn_new::<RcFnBrand, _, _>(|s: i32| Ok(s)),
		/// 	lift_fn_new::<RcFnBrand, _, _>(|(_s, b): (i32, i32)| b),
		/// );
		/// let lifted = <StallBrand<RcFnBrand, i32, i32> as Strong>::first::<i32, i32, String>(stall);
		/// assert_eq!((lifted.get)((10, "hi".to_string())), Ok(10));
		/// ```
		fn first<'a, S: 'a, T: 'a, C: 'a>(
			pab: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, S, T>)
		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, (S, C), (T, C)>) {
			let get = pab.get;
			let set = pab.set;
			Stall::new(
				<FunctionBrand as LiftFn>::new(move |(s, c): (S, C)| (*get)(s).map_err(|t| (t, c))),
				<FunctionBrand as LiftFn>::new(move |((s, c), b): ((S, C), B)| ((*set)((s, b)), c)),
			)
		}
	}

	#[document_type_parameters(
		"The cloneable function brand.",
		"The type of the value produced by the preview function.",
		"The type of the value consumed by the setter."
	)]
	impl<FunctionBrand: LiftFn + 'static, A: 'static, B: 'static> Choice
		for StallBrand<FunctionBrand, A, B>
	{
		/// Lifts the `Stall` profunctor to operate on the left component of a `Result`.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the functions.",
			"The source type of the structure.",
			"The target type of the structure.",
			"The type of the other component."
		)]
		///
		#[document_parameters("The stall instance to transform.")]
		#[document_returns(
			"A transformed `Stall` instance that operates on the left component of a `Result`."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		optics::*,
		/// 		*,
		/// 	},
		/// 	classes::{
		/// 		clone_fn::new as lift_fn_new,
		/// 		optics::*,
		/// 		profunctor::*,
		/// 	},
		/// 	types::optics::*,
		/// };
		///
		/// let stall = Stall::<RcFnBrand, i32, i32, i32, i32>::new(
		/// 	lift_fn_new::<RcFnBrand, _, _>(|s: i32| Ok(s)),
		/// 	lift_fn_new::<RcFnBrand, _, _>(|(_s, b): (i32, i32)| b),
		/// );
		/// let lifted = <StallBrand<RcFnBrand, i32, i32> as Choice>::left::<i32, i32, String>(stall);
		/// assert!((lifted.get)(Err(10)).is_ok());
		/// ```
		fn left<'a, S: 'a, T: 'a, C: 'a>(
			pab: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, S, T>)
		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, Result<C, S>, Result<C, T>>)
		{
			let get = pab.get;
			let set = pab.set;
			Stall::new(
				<FunctionBrand as LiftFn>::new(move |r: Result<C, S>| match r {
					Err(s) => (*get)(s).map_err(Err),
					Ok(c) => Err(Ok(c)),
				}),
				<FunctionBrand as LiftFn>::new(move |(r, b): (Result<C, S>, B)| match r {
					Err(s) => Err((*set)((s, b))),
					Ok(c) => Ok(c),
				}),
			)
		}

		/// Lifts the `Stall` profunctor to operate on the right component of a `Result`.
		#[document_signature]
		#[document_type_parameters(
			"The lifetime of the functions.",
			"The source type of the structure.",
			"The target type of the structure.",
			"The type of the other component."
		)]
		///
		#[document_parameters("The stall instance to transform.")]
		#[document_returns(
			"A transformed `Stall` instance that operates on the right component of a `Result`."
		)]
		///
		#[document_examples]
		///
		/// ```
		/// use fp_library::{
		/// 	brands::{
		/// 		optics::*,
		/// 		*,
		/// 	},
		/// 	classes::{
		/// 		clone_fn::new as lift_fn_new,
		/// 		optics::*,
		/// 		profunctor::*,
		/// 	},
		/// 	types::optics::*,
		/// };
		///
		/// let stall = Stall::<RcFnBrand, i32, i32, i32, i32>::new(
		/// 	lift_fn_new::<RcFnBrand, _, _>(|s| Ok(s)),
		/// 	lift_fn_new::<RcFnBrand, _, _>(|(_, b)| b),
		/// );
		/// let lifted = <StallBrand<RcFnBrand, i32, i32> as Choice>::right::<i32, i32, i32>(stall);
		/// assert_eq!((lifted.get)(Ok(42)), Ok(42));
		/// ```
		fn right<'a, S: 'a, T: 'a, C: 'a>(
			pab: Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, S, T>)
		) -> Apply!(<Self as Kind!( type Of<'a, T: 'a, U: 'a>: 'a; )>::Of<'a, Result<S, C>, Result<T, C>>)
		{
			let get = pab.get;
			let set = pab.set;
			Stall::new(
				<FunctionBrand as LiftFn>::new(move |r: Result<S, C>| match r {
					Ok(s) => (*get)(s).map_err(Ok),
					Err(c) => Err(Err(c)),
				}),
				<FunctionBrand as LiftFn>::new(move |(r, b): (Result<S, C>, B)| match r {
					Ok(s) => Ok((*set)((s, b))),
					Err(c) => Err(c),
				}),
			)
		}
	}
}
pub use inner::*;