src/instance.rs

/*!
Helper traits to work with references or owned values of types and their subsets.
*/

#[derive(Clone, Copy)]
pub enum EitherDecomp<A, B> {
    Owned(A),
    Borrowed(B),
}

/// A very basic implementation of [`std::borrow::Cow`] without a [`Clone`] trait dependency.
pub type MyCow<'b, X> = EitherDecomp<X, &'b X>;

impl<'b, X> std::ops::Deref for MyCow<'b, X> {
    type Target = X;

    #[inline]
    fn deref(&self) -> &Self::Target {
        match self {
            EitherDecomp::Owned(x) => &x,
            EitherDecomp::Borrowed(x) => x,
        }
    }
}

impl<'b, X> MyCow<'b, X> {
    #[inline]
    pub fn into_owned(self) -> X
    where
        X: Clone,
    {
        match self {
            EitherDecomp::Owned(x) => x,
            EitherDecomp::Borrowed(x) => x.clone(),
        }
    }
}

/// Trait for abitrary mathematical spaces.
pub trait Space: Instance<Self, Self::Decomp> {
    /// Default decomposition for the space
    type Decomp: Decomposition<Self>;
}

#[macro_export]
macro_rules! impl_basic_space {
    ($($type:ty)*) => { $(
        impl $crate::instance::Space for $type {
            type Decomp = $crate::instance::BasicDecomposition;
        }
    )* };
    ($type:ty where $($where:tt)*) => {
        impl<$($where)*> $crate::instance::Space for $type {
            type Decomp = $crate::instance::BasicDecomposition;
        }
    };
}

impl_basic_space!(u8 u16 u32 u64 u128 usize
                  i8 i16 i32 i64 i128 isize
                  f32 f64);

/// Marker type for decompositions to be used with [`Instance`].
pub trait Decomposition<X: Space>: Sized {
    /// The composition
    type Decomposition<'b>: Instance<X, Self>
    where
        X: 'b;
}

/// Most common [`Decomposition`] (into `Either<X, &'b X>`) that allows working with owned
/// values and all sorts of references.
#[derive(Copy, Clone, Debug)]
pub struct BasicDecomposition;

impl<X: Space + Clone> Decomposition<X> for BasicDecomposition {
    type Decomposition<'b>
        = MyCow<'b, X>
    where
        X: 'b;
}

pub trait Instantiated<X: Space, D = <X as Space>::Decomp>: Instance<X, D>
where
    D: Decomposition<X>,
{
    type RefInstance<'b>: Instance<X, D> + Copy
    where
        Self: 'b;

    fn ref_inst(&self) -> Self::RefInstance<'_>;
}

impl<X: Space> Instantiated<X, BasicDecomposition> for X
where
    X: Instance<X, BasicDecomposition> + Clone,
    for<'b> &'b X: Instance<X, BasicDecomposition>,
{
    type RefInstance<'b>
        = &'b X
    where
        Self: 'b;

    fn ref_inst(&self) -> Self::RefInstance<'_> {
        self
    }
}

/// Helper trait for functions to work with either owned values or references to either the
/// “principal type” `X` or types some present a subset of `X`. In the latter sense, this
/// generalises [`std::borrow::ToOwned`], [`std::borrow::Borrow`], and [`std::borrow::Cow`].
///
/// This is used, for example, by [`crate::mapping::Mapping::apply`].
pub trait Instance<X: Space, D = <X as Space>::Decomp>: Sized
where
    D: Decomposition<X>,
{
    type Instantiated: Space + Instantiated<X, D>;

    /// Decomposes self according to `decomposer`, and evaluate `f` on the result.
    /// Consumes self.
    fn eval_decompose<'b, R>(self, f: impl FnOnce(D::Decomposition<'b>) -> R) -> R
    where
        X: 'b,
        Self: 'b;

    /// Does a light decomposition of self `decomposer`, and evaluates `f` on the result.
    /// Does not consume self.
    fn eval_ref_decompose<'b, R>(&'b self, f: impl FnOnce(D::Decomposition<'b>) -> R) -> R
    where
        X: 'b,
        Self: 'b;

    /// Returns an owned instance of `X`, cloning or converting non-true instances when necessary.
    fn own(self) -> X;

    /// Instantiate to something that can be 'referenced'.
    ///
    /// This is distinct from [`own`], as it is not guaranteed that `&'b X` is an
    /// [`Instance`] of `X`.
    fn instantiate(self) -> Self::Instantiated;

    // ************** automatically implemented methods below from here **************

    /// Evaluate `f` on the result of [`instantiate`]ing self, and then referencing.
    fn eval_inst_ref<R>(
        self,
        f: impl for<'b> FnOnce(<Self::Instantiated as Instantiated<X, D>>::RefInstance<'b>) -> R,
    ) -> R {
        let inst = self.instantiate();
        f(inst.ref_inst())
    }

    /// Returns an owned instance or reference to `X`, converting non-true instances when necessary.
    ///
    /// Default implementation uses [`Self::own`]. Consumes the input.
    fn cow<'b>(self) -> MyCow<'b, X>
    where
        Self: 'b,
    {
        MyCow::Owned(self.own())
    }

    #[inline]
    /// Evaluates `f` on a reference to self.
    ///
    /// Default implementation uses [`Self::cow`]. Consumes the input.
    fn eval<'b, R>(self, f: impl FnOnce(&X) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(&*self.cow())
    }

    #[inline]
    /// Evaluates `f` or `g` depending on whether a reference or owned value is available.
    ///
    /// Default implementation uses [`Self::cow`]. Consumes the input.
    fn either<'b, R>(self, f: impl FnOnce(X) -> R, g: impl FnOnce(&X) -> R) -> R
    where
        Self: 'b,
    {
        match self.cow() {
            EitherDecomp::Owned(x) => f(x),
            EitherDecomp::Borrowed(x) => g(x),
        }
    }
}

impl<X: Space + Clone> Instance<X, BasicDecomposition> for X {
    type Instantiated = X;

    fn instantiate(self) -> Self::Instantiated {
        self
    }

    #[inline]
    fn eval_decompose<'b, R>(self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(MyCow::Owned(self))
    }

    #[inline]
    fn eval_ref_decompose<'b, R>(&'b self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(MyCow::Borrowed(&self))
    }

    #[inline]
    fn own(self) -> X {
        self
    }

    #[inline]
    fn cow<'b>(self) -> MyCow<'b, X>
    where
        Self: 'b,
    {
        MyCow::Owned(self)
    }
}

impl<'a, X: Space + Clone> Instance<X, BasicDecomposition> for &'a X {
    type Instantiated = X;

    fn instantiate(self) -> Self::Instantiated {
        self.own()
    }

    #[inline]
    fn eval_decompose<'b, R>(self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(MyCow::Borrowed(self))
    }

    #[inline]
    fn eval_ref_decompose<'b, R>(&'b self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(MyCow::Borrowed(self))
    }

    #[inline]
    fn own(self) -> X {
        self.clone()
    }

    #[inline]
    fn cow<'b>(self) -> MyCow<'b, X>
    where
        Self: 'b,
    {
        MyCow::Borrowed(self)
    }
}

impl<'a, X: Space + Clone> Instance<X, BasicDecomposition> for &'a mut X {
    type Instantiated = X;

    fn instantiate(self) -> Self::Instantiated {
        self.own()
    }

    #[inline]
    fn eval_decompose<'b, R>(self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(EitherDecomp::Borrowed(self))
    }

    #[inline]
    fn eval_ref_decompose<'b, R>(&'b self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(EitherDecomp::Borrowed(self))
    }

    #[inline]
    fn own(self) -> X {
        self.clone()
    }

    #[inline]
    fn cow<'b>(self) -> MyCow<'b, X>
    where
        Self: 'b,
        X: Clone,
    {
        EitherDecomp::Borrowed(self)
    }
}

impl<'a, X: Space + Clone> Instance<X, BasicDecomposition> for MyCow<'a, X> {
    type Instantiated = X;

    fn instantiate(self) -> Self::Instantiated {
        self.own()
    }

    #[inline]
    fn eval_decompose<'b, R>(self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        f(self)
    }

    #[inline]
    fn eval_ref_decompose<'b, R>(&'b self, f: impl FnOnce(MyCow<'b, X>) -> R) -> R
    where
        X: 'b,
        Self: 'b,
    {
        match self {
            MyCow::Borrowed(a) => f(MyCow::Borrowed(a)),
            MyCow::Owned(b) => f(MyCow::Borrowed(&b)),
        }
    }

    #[inline]
    fn own(self) -> X {
        match self {
            MyCow::Borrowed(a) => a.own(),
            MyCow::Owned(b) => b.own(),
        }
    }

    #[inline]
    fn cow<'b>(self) -> MyCow<'b, X>
    where
        Self: 'b,
    {
        match self {
            MyCow::Borrowed(a) => a.cow(),
            MyCow::Owned(b) => b.cow(),
        }
    }
}

/// Marker type for mutable decompositions to be used with [`InstanceMut`].
pub trait DecompositionMut<X: Space>: Sized {
    type ReferenceMut<'b>: InstanceMut<X, Self>
    where
        X: 'b;
}

/// Helper trait for functions to work with mutable references.
pub trait InstanceMut<X: Space, D = <X as Space>::Decomp>: Sized
where
    D: DecompositionMut<X>,
{
    /// Returns a mutable decomposition of self.
    fn ref_instance_mut(&mut self) -> D::ReferenceMut<'_>;
}

impl<X: Space> DecompositionMut<X> for BasicDecomposition {
    type ReferenceMut<'b>
        = &'b mut X
    where
        X: 'b;
}

/// This impl may seem pointless, but allows throwaway mutable scratch variables
impl<'a, X: Space> InstanceMut<X, BasicDecomposition> for X {
    #[inline]
    fn ref_instance_mut(
        &mut self,
    ) -> <BasicDecomposition as DecompositionMut<X>>::ReferenceMut<'_> {
        self
    }
}

impl<'a, X: Space> InstanceMut<X, BasicDecomposition> for &'a mut X {
    #[inline]
    fn ref_instance_mut(
        &mut self,
    ) -> <BasicDecomposition as DecompositionMut<X>>::ReferenceMut<'_> {
        self
    }
}