dungeon_cell/

bound.rs

//! Type encoded dynamic trait bounds.
//!
//! [`dungeon_cell`][crate] uses generic types for configuration.
//! Part of this configuration is what traits a type stored in a
//! [`dungeon_cell`][crate] type require.
//!
//! An example is wanting a [`DungeonCore`][crate::DungeonCore] to
//! be [`Send`][std::marker::Send]. To allow this, all types the `DungeonCore` can store
//! must implement `Send`. This is expressed using the following
//! trait bound. The `bounds::Send` would be part of the `DungeonCore`'s
//! generics.
//! ```ignore
//! where
//!     T: Dynamic<bounds::Send>
//! ```
//!
//! See the [`traits`] module for the supported traits.
//! Only a small collection of traits are supported because of how the encoding has to be setup for
//! rustc to understand it. The chosen traits are all from `core` and are the most commonly used
//! and implemented.
//!
//! # Subtraiting and Variance
//!
//! In Rust, a trait bound is of the form `T: X + Y + Z` which means the type
//! `T` must implement traits `X`, `Y`, and `Z`. It doesn't say those are
//! the only traits that type `T` implements. Additionally, there isn't a way
//! in stable Rust to bound on a type `T` **not** implementing a type.
//!
//! This module encodes trait bounds as types. Because of this encoding we
//! can ask questions about the trait bound in the type system. The four questions
//! we can ask about a bound `A` are:
//! - is the bound `B` the same as `A`,
//! - is the bound `B` a subset of `A`,
//! - is the bound `B` a superset of `A`,
//! - is the bound `B` disjoint from `A`.
//!
//! The first question is provided by `B: Equal<A>` and simply checks that `A`
//! and `B` are the same type.
//!
//! For example of the second question, given the bound `A` of the form `X + Y + Z`,
//! and bound `B` of the form `X + Z`, the bound `B` is a subset of `A`. A subset bound
//! is a bound that requires **less** when used to bound a type. The `B: Subset<A>` trait bound
//! allows checking this.
//!
//! For example of the third question, given the bound `A` of the form `X + Y`,
//! and bound `B` of the form `X + Y + Z`, the bound `B` is a superset of `A`.
//! A subset bound is a bound that requires **more** when used to bound a type.
//! In reality this is the inverse of the subset question so if we switch `A` and `B`
//! we get: is `A` a subset of `B`.
//!
//! For example of the forth question, given the bound `A` of the form `X + Y`,
//! and bound `B` of the form `Z`, the bound `B` is disjoint from `A`.
//! A disjoint bound is a bound that requires **different** functionality when
//! used to bound a type. The `B: Disjoint<A>` trait allows checking this.

mod disjoint;
mod equal;
mod subset;

use core::fmt::Formatter;
use core::marker::PhantomData;

use crate::marker_traits::IsBound;

pub use disjoint::Disjoint;
pub use equal::Equal;
pub use subset::Subset;

/// Markers for traits that can be used in a dynamic trait bound.
///
/// See the [`bounds`] module for a collection pf predefined bounds
/// built from these markers.
///
/// The supported traits are:
/// - [`Send`][std::marker::Send]
/// - [`Sync`][std::marker::Sync]
/// - [`Copy`][std::marker::Copy]
/// - [`Clone`][std::clone::Clone]
/// - [`Unpin`][std::marker::Unpin]
/// - [`Debug`][std::fmt::Debug]
///
/// The special marker `__` signifies that a trait is **not** included in the dynamic bound.
pub mod traits {
    /// Marker for a trait not being bounded on.
    #[derive(Copy, Clone, Debug)]
    pub enum __ {}

    /// Marker for `Send`.
    #[derive(Copy, Clone, Debug)]
    pub enum Send {}

    /// Marker for `Sync`.
    #[derive(Copy, Clone, Debug)]
    pub enum Sync {}

    /// Marker for `Copy`.
    #[derive(Copy, Clone, Debug)]
    pub enum Copy {}

    /// Marker for `Clone`.
    #[derive(Copy, Clone, Debug)]
    pub enum Clone {}

    /// Marker for `Unpin`.
    #[derive(Copy, Clone, Debug)]
    pub enum Unpin {}

    /// Marker for `Debug`.
    #[derive(Copy, Clone, Debug)]
    pub enum Debug {}
}

/// Predefined dynamic trait bounds.
///
/// A custom trait bound can be made by defining a type alias
/// and using [`Bound`] along with the markers in the [`traits`] module.
/// The order of the markers needs to match the definition of [`Bound`].
/// ```
/// use dungeon_cell::bound::{Bound, traits};
/// use dungeon_cell::bound::traits::__;
///
/// type MyBound = Bound<traits::Send, __, traits::Copy, __, __, __>;
/// ```
pub mod bounds {
    use super::traits::__;
    use super::{traits, Bound};

    /// No bounds.
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Empty;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// // all types can be bounded by Empty
    /// test::<(), Empty>();
    /// test::<i32, Empty>();
    /// test::<String, Empty>();
    /// ```
    pub type Empty = Bound<__, __, __, __, __, __>;

    /// Bound for [`Send`][std::marker::Send].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Send;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Send>();
    /// test::<i32, Send>();
    /// test::<String, Send>();
    /// ```
    pub type Send = Bound<traits::Send, __, __, __, __, __>;

    /// Bound for [`Sync`][std::marker::Sync].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Sync;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Sync>();
    /// test::<i32, Sync>();
    /// test::<String, Sync>();
    /// ```
    pub type Sync = Bound<__, traits::Sync, __, __, __, __>;

    /// Bound for [`Copy`][std::marker::Copy].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Copy;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Copy>();
    /// test::<i32, Copy>();
    /// test::<&str, Copy>();
    /// ```
    pub type Copy = Bound<__, __, traits::Copy, __, __, __>;

    /// Bound for [`Clone`][std::clone::Clone].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Clone;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Clone>();
    /// test::<i32, Clone>();
    /// test::<String, Clone>();
    /// ```
    pub type Clone = Bound<__, __, __, traits::Clone, __, __>;

    /// Bound for [`Unpin`][std::marker::Unpin].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Unpin;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Unpin>();
    /// test::<i32, Unpin>();
    /// test::<String, Unpin>();
    /// ```
    pub type Unpin = Bound<__, __, __, __, traits::Unpin, __>;

    /// Bound for [`Debug`][std::fmt::Debug].
    ///
    /// # Examples
    /// ```
    /// use dungeon_cell::bound::bounds::Debug;
    /// use dungeon_cell::bound::Dynamic;
    /// use dungeon_cell::marker_traits::IsBound;
    ///
    /// fn test<T: Dynamic<B>, B: IsBound>() {}
    ///
    /// test::<(), Debug>();
    /// test::<i32, Debug>();
    /// test::<String, Debug>();
    /// ```
    pub type Debug = Bound<__, __, __, __, __, traits::Debug>;

    /// Bound for `Sync + Send`.
    pub type SyncSend = Bound<traits::Send, traits::Sync, __, __, __, __>;

    /// Bound for `Send + Sync`.
    pub type SendSync = SyncSend;

    /// Bound for `Clone + Copy`.
    pub type CloneCopy = Bound<__, __, traits::Copy, traits::Clone, __, __>;

    /// Bound for `Copy + Clone`. Same as [`CopyClone`].
    pub type CopyClone = CloneCopy;

    /// Bound that most types satisfy `Send + Sync + Unpin + Debug`.
    pub type Normal =
        Bound<traits::Send, traits::Sync, __, __, traits::Unpin, traits::Debug>;

    /// Bound for implementing the auto traits `Send + Sync + Unpin`.
    pub type AutoTraits =
        Bound<traits::Send, traits::Sync, __, __, traits::Unpin, __>;
}

/// Type encoded trait bound.
///
/// This is the type to use where a [`IsBound`] generic is required.
///
/// See the [`bounds`] module for a collection of predefined bounds.
///
/// Using this type in combination with [`Dynamic`] allows for applying a trait bound
/// based on a generic type.
/// ```
/// use dungeon_cell::bound::{Dynamic, bounds};
///
/// fn test<T: Dynamic<bounds::Normal>>() {}
///
/// test::<String>();
/// ```
#[derive(Copy, Clone, Debug)]
pub struct Bound<Send, Sync, Copy, Clone, Unpin, Debug> {
    _phantom: PhantomData<(Send, Sync, Copy, Clone, Unpin, Debug)>,
}

/// Trait implemented when the bound given by `B` is satisfied by `Self`.
///
/// Use this trait in combination with [`Bound`] to apply a trait bound
/// based on a generic type.
/// ```compile_fail
/// use dungeon_cell::bound::{Dynamic, bounds};
/// use dungeon_cell::marker_traits::IsBound;
///
/// fn test<T: Dynamic<B>, B: IsBound>() {}
///
/// // this failes because String isn't Copy
/// test::<String, bounds::Copy>();
/// ```
///
/// The traits with functionality ([`Clone`][std::clone::Clone] and [`Debug`][std::fmt::Debug])
/// have their implementation for the type available as [`Self::clone()`] and [`Self::debug()`]. If
/// the type doesn't implement one or both of these traits then it's method will be implemented
/// with [`unreachable_unchecked()`][std::hint::unreachable_unchecked].
///
/// This trait is [sealed](https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed)
/// and cannot be implemented outside of the implementations here.
pub trait Dynamic<B: IsBound>: Sealed<B> {
    /// Call the [`Clone::clone()`][std::clone::Clone::clone] implementation of [`Self`].
    ///
    /// This method is always safe to call because it's bounded by the bound including
    /// `Clone`. To emulate specialization, use [`Self::clone_unchecked`] and check
    /// the `B::BOUND_BY_CLONE` flag at runtime.
    fn clone(this: &Self) -> Self
    where
        Self: Sized,
        <B as IsBound>::CloneMarker: Clone,
    {
        // SAFETY: We have checked that B::CloneMarker: Clone.
        unsafe { Self::clone_unchecked(this) }
    }

    /// Call the [`Debug::fmt()`][std::fmt::Debug::fmt] implementation of [`Self`].
    ///
    /// This method is always safe to call because it's bounded by the bound including
    /// `Debug`. To emulate specialization, use [`Self::debug_unchecked`] and check
    /// the `B::BOUND_BY_DEBUG` flag at runtime.
    fn debug(this: &Self, f: &mut Formatter<'_>) -> Result<(), core::fmt::Error>
    where
        Self: Sized,
        <B as IsBound>::DebugMarker: ::core::fmt::Debug,
    {
        // SAFETY: We have checked that B::DebugMarker: Debug.
        unsafe { Self::debug_unchecked(this, f) }
    }

    /// Unsafe form of [`Self::clone()`].
    ///
    /// This method is only valid to call if `B` has `Clone` as part of it's bound.
    ///
    /// # Safety
    /// This function must only be called if [`B::BOUND_BY_CLONE`][IsBound::BOUND_BY_CLONE] == `true` and/or [`B::CloneMarker`][IsBound::CloneMarker]: [`Clone`][std::clone::Clone].
    unsafe fn clone_unchecked(this: &Self) -> Self
    where
        Self: Sized;

    /// Unsafe form of [`Self::debug()`].
    ///
    /// This method is only valid to call if `B` has `Debug` as part of it's bound.
    ///
    /// # Safety
    /// This function must only be called if [`B::BOUND_BY_DEBUG`][IsBound::BOUND_BY_DEBUG] == `true` and/or [`B::DebugMarker`][IsBound::DebugMarker]: [`Debug`][std::fmt::Debug].
    unsafe fn debug_unchecked(
        this: &Self,
        f: &mut Formatter<'_>,
    ) -> Result<(), core::fmt::Error>;
}

use sealed::Sealed;

mod sealed {
    use super::*;
    use crate::unreachable;

    pub trait Sealed<T> {}

    impl<T> Sealed<bounds::Empty> for T {}
    impl<T> Dynamic<bounds::Empty> for T {
        unsafe fn clone_unchecked(_this: &Self) -> T {
            // SAFETY: This method will not be called when `Self`
            // isn't bound by `Clone`.
            unsafe { unreachable() };
        }

        unsafe fn debug_unchecked(
            _this: &Self,
            _f: &mut Formatter<'_>,
        ) -> Result<(), core::fmt::Error> {
            // SAFETY: This method will not be called when `Self`
            // isn't bound by `Debug`.
            unsafe { unreachable() };
        }
    }

    macro_rules! bound_impl {
        (@send, __) => {};
        (@sync, __) => {};
        (@copy, __) => {};
        (@unpin, __) => {};
        (@send, Send) => {};
        (@sync, Sync) => {};
        (@copy, Copy) => {};
        (@unpin, Unpin) => {};
        (@clone, __) => {
            unsafe fn clone_unchecked(_this: &Self) -> T {
                // SAFETY: This method will not be called when `Self`
                // isn't bound by `Clone`.
                unsafe { unreachable() };
            }
        };
        (@clone, Clone) => {
            unsafe fn clone_unchecked(this: &Self) -> T {
                Clone::clone(this)
            }
        };
        (@debug, __) => {
            unsafe fn debug_unchecked(
                _this: &Self,
                _f: &mut Formatter<'_>,
            ) -> Result<(), core::fmt::Error> {
                // SAFETY: This method will not be called when `Self`
                // isn't bound by `Debug`.
                unsafe { unreachable() };
            }
        };
        (@debug, Debug) => {
            unsafe fn debug_unchecked(
                this: &Self,
                f: &mut Formatter<'_>,
            ) -> Result<(), core::fmt::Error> {
                core::fmt::Debug::fmt(this, f)
            }
        };
    }

    macro_rules! powerset {
        (
            @helper
            $empty:ident
            []
            [$($bounds:ident),*]
        ) => {
        };
        (
            @helper
            $empty:ident
            [$trait:ident $(, $traits:ident)*]
            [$send:ident, $sync:ident, $copy:ident, $clone:ident, $unpin:ident, $debug:ident]
        ) => {
            impl<T: $trait $(+ $traits)*> Sealed<Bound<
              traits::$send, traits::$sync, traits::$copy, traits::$clone, traits::$unpin, traits::$debug
            >> for T {
            }

            impl<T: $trait $(+ $traits)*> Dynamic<Bound<
              traits::$send, traits::$sync, traits::$copy, traits::$clone, traits::$unpin, traits::$debug
            >> for T {
                bound_impl!(@clone, $clone);
                bound_impl!(@debug, $debug);
                bound_impl!(@send, $send);
                bound_impl!(@sync, $sync);
                bound_impl!(@copy, $copy);
                bound_impl!(@unpin, $unpin);
            }
        };
        // @helper [traitB, traitD] [(boundA, false), (boundB, true), (boundC, false), (boundD, true)] bound => trait, ...
        (
            @helper
            $empty:ident
            [$($trait:ident),*]
            [$($bound:ident),*]
            $next_trait:ident
            $(, $traits:ident)*
        ) => {
            powerset!(@helper $empty [$($trait),*] [$($bound,)* $empty] $($traits),*);
            powerset!(@helper $empty [$($trait,)* $next_trait] [$($bound,)* $next_trait] $($traits),*);
        };
        ($empty:ident, $($trait:ident),*) => {
            powerset!(@helper $empty [] [] $($trait),*);
        };
    }

    use core::fmt::Debug;

    powerset![__, Send, Sync, Copy, Clone, Unpin, Debug];
}