supply 0.2.0

//! [`Any`](core::any::Any) like API but with any number of lifetimes.
//!
//! The [`Anything`] trait when used as a trait object can represent any type
//! including ones containing lifetimes. This is not possible with the normal
//! [`Any`](core::any::Any) trait. The possible lifetimes the value could be using
//! are tracked via an extra `L` generic. See the [`lt_list`](crate::lt_list)
//! module for more information about these lifetime lists.
//!
//! Unlike the provide API, [`Anything`] doesn't work with arbitrary tags.
//! Instead a type must implement [`Reify`] to itself. Most `core`/`alloc`/`std`
//! types do this already, but for custom types they need to implement
//! [`Tagged`]. Additionally, `'static` types can be wrapped in [`AnyStatic`] instead
//! of implementing [`Tagged`].
//!
//! # Examples
//! ```
//! # #[cfg(feature = "std")]
//! # fn __() {
//! use core::fmt::Debug;
//! use supply::prelude::*;
//!
//! // Logger function for any type that implements `Debug`.
//! fn log<'r, T: ?Sized + Anything<l!['r]> + Debug>(value: &'r T) -> String {
//!     // Try to convert our value to a `String` or a `&'r str`. If successful, we want to
//!     // output the `String`'s length as well as its value. If not, it's a
//!     // different type: just print it out unadorned.
//!
//!     if let Some(as_string) = value.downcast_ref::<String>() {
//!         return format!("String ({}): {}", as_string.len(), as_string);
//!     }
//!
//!     if let Some(as_str) = value.downcast_ref::<&str>() {
//!         return format!("str ({}): {}", as_str.len(), as_str);
//!     }
//!
//!     format!("{value:?}")
//! }
//!
//! // This function wants to log its parameter out prior to doing work with it.
//! fn do_work<'r, T: Anything<l!['r]> + Debug>(value: &'r T) -> String {
//!     log(value)
//!     // ...do some other work
//! }
//!
//! fn main() {
//!     let my_string = "Hello World".to_string();
//!     let r = do_work(&my_string);
//!     assert_eq!(r, "String (11): Hello World");
//!
//!     let my_i8: i8 = 100;
//!     let r = do_work(&my_i8);
//!     assert_eq!(r, "100");
//!
//!     let my_str = "Bye World";
//!     let r = do_work(&my_str);
//!     assert_eq!(r, "str (9): Bye World");
//! }
//! # }
//! # #[cfg(feature = "std")]
//! # { __(); }
//! ```
//! <sub>
//!
//! This example is modified from <https://doc.rust-lang.org/std/any/index.html#examples>
//!
//! </sub>

use crate::lt_list::{Lt0, Lt1, LtHoleList, LtList};
use crate::tag::{Reify, ReifySized, Tag, TagTypeId, Tagged, WithLt};
use crate::{lt_structure, Want};

/// [`Any`](core::any::Any) like trait with support for arbitrary number of lifetimes.
///
/// See [`AnythingExt`] for more methods types that implement this trait get.
///
/// This trait is implemented for everything that can.
pub trait Anything<L: LtList = Lt0>: anything_seal::Sealed<L> {
    /// Get the [`TagTypeId`] of `self`.
    ///
    /// When called on a trait object this returns the `TagTypeId` of the underlying
    /// concrete type not that of the trait object.
    ///
    /// # Examples
    /// ```
    /// # #[cfg(feature = "std")]
    /// # fn __() {
    /// use supply::prelude::*;
    ///
    /// fn is_str<'s>(s: &dyn Anything<l!['s]>) -> bool {
    ///     TagTypeId::of::<&str>() == s.tag_id()
    /// }
    ///
    /// assert_eq!(is_str(&0), false);
    ///
    /// let s = "cookie monster".to_string();
    /// assert_eq!(is_str(&s), false);
    /// assert_eq!(is_str(&s.as_str()), true);
    ///
    /// assert_eq!(is_str(&"hello world"), true);
    /// # }
    /// # #[cfg(feature = "std")]
    /// # { __(); }
    /// ```
    /// <sub>
    ///
    /// This example is modified from <https://doc.rust-lang.org/std/any/trait.Any.html#examples>
    ///
    /// </sub>
    fn tag_id(&self) -> TagTypeId<L>;

    fn try_fulfill_want<'r>(&'r self, want: &mut dyn Want<Lt1<'r, L>>) -> bool;
}

/// Generic methods for types implementing [`Anything`].
///
/// This trait provides downcasting methods to anything that implements [`Anything`]
/// including trait objects with it as a super trait.
pub trait AnythingExt<L: LtList = Lt0>: Anything<L> {
    /// Returns `true` if the type is the same as `T`.
    ///
    /// On trait objects this checks the inner type not the trait object itself.
    ///
    /// # Examples
    /// ```
    /// use supply::prelude::*;
    ///
    /// trait MyTrait: Anything {}
    /// impl MyTrait for i32 {}
    ///
    /// let x: &dyn MyTrait = &42;
    /// assert!(x.is::<i32>());
    /// ```
    fn is<T>(&self) -> bool
    where
        T: ?Sized + Reify<L>,
    {
        self.tag_id() == TagTypeId::<L>::of::<T>()
    }

    /// Returns a borrow of the inner value if it is of type `T`, or `None` if it isn't.
    ///
    /// # Examples
    ///
    /// ```
    /// use supply::prelude::*;
    ///
    /// fn print_if_str(s: &dyn Anything<l!['_]>) -> String {
    ///     if let Some(string) = s.downcast_ref::<&str>() {
    ///         format!("It's a str ({}): '{}'", string.len(), string)
    ///     } else {
    ///         format!("Not a str...")
    ///     }
    /// }
    ///
    /// assert_eq!(print_if_str(&0), "Not a str...");
    /// assert_eq!(print_if_str(&"cookie monster"), "It's a str (14): 'cookie monster'");
    /// ```
    fn downcast_ref<T>(&self) -> Option<&T::Reified>
    where
        T: ?Sized + ReifySized<L>,
    {
        if self.is::<T>() {
            Some(unsafe { &*(self as *const _ as *const T::Reified) })
        } else {
            None
        }
    }

    /// Returns a mutable borrow of the inner value if it is of type `T`, or `None` if it isn't.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[cfg(feature = "std")]
    /// # fn __() {
    /// use supply::prelude::*;
    ///
    /// fn modify_if_u32(s: &mut dyn Anything) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// # }
    /// # #[cfg(feature = "std")]
    /// # { __(); }
    /// ```
    fn downcast_mut<T: ?Sized + ReifySized<L>>(&mut self) -> Option<&mut T::Reified> {
        if self.is::<T>() {
            Some(unsafe { &mut *(self as *mut _ as *mut T::Reified) })
        } else {
            None
        }
    }

    /// Returns the inner value if it is of type `T`, or `self` if it isn't.
    ///
    /// This method is mainly useful for emulating specialization in generic functions.
    ///
    /// # Examples
    ///
    /// ```
    /// use supply::prelude::*;
    ///
    /// fn print_if_str<'r, T: Anything<l!['r]>>(s: T) -> String {
    ///     if let Ok(string) = s.downcast_move::<&str>() {
    ///         format!("It's a str ({}): '{}'", string.len(), string)
    ///     } else {
    ///         format!("Not a str...")
    ///     }
    /// }
    ///
    /// assert_eq!(print_if_str(0), "Not a str...");
    /// assert_eq!(print_if_str("cake"), "It's a str (4): 'cake'");
    /// ```
    fn downcast_move<T: ?Sized + ReifySized<L>>(self) -> Result<T::Reified, Self>
    where
        Self: Sized,
    {
        if self.is::<T>() {
            // can't use `Option` trick here like with `Any`
            let this = core::mem::MaybeUninit::new(self);
            Ok(unsafe { core::mem::transmute_copy(&this) })
        } else {
            Err(self)
        }
    }
}

mod anything_seal {
    use super::*;

    pub trait Sealed<L: LtList> {}

    impl<L: LtList, T: ?Sized + Reify<L, Reified = T>> Sealed<L> for T {}
}

// The Reified = T here must be there for the downcast to be valid.
// This is different to the provide API because we are going to downcast from *T*
// as its the one implementing Anything. Whereas the provide API works on the reified
// type. Here there is nowhere for a tag to live.
impl<L: LtList, T: ?Sized + Reify<L, Reified = T>> Anything<L> for T {
    fn tag_id(&self) -> TagTypeId<L> {
        TagTypeId::of::<T>()
    }

    fn try_fulfill_want<'r>(&'r self, want: &mut dyn Want<Lt1<'r, L>>) -> bool {
        if let Some(want) = want.try_for::<&T>() {
            want.fulfill(self);
            true
        } else {
            false
        }
    }
}

impl<L: LtList, T: ?Sized + Anything<L>> AnythingExt<L> for T {}

// Tag the trait object of Anything for any lifetime list.
const _: () = {
    pub struct AnythingTag<L>(L);

    impl<'u, L: LtList> WithLt<Lt1<'u, L>> for AnythingTag<<Lt1<'u, L> as LtList>::Tag> {
        type Reified = dyn Anything<L> + 'u;
    }

    impl<L: LtHoleList> Tag for AnythingTag<L> {
        type LifetimesTag = L;
    }

    impl<L: LtHoleList> Tagged for AnythingTag<L> {
        type Tag = Self;
    }

    impl<'u, L: LtList> Tagged for dyn Anything<L> + 'u {
        type Tag = AnythingTag<<Lt1<'u, L> as LtList>::Tag>;
    }
};

/// Transparent wrapper for `'static` types to work with [`Anything`].
///
/// Do to limitations of Rust, custom `'static` types can't work out of the box
/// with [`Anything`]. There are two ways to make them.
///
/// 1. Use this wrapper to convert a `&T` to a `&AnyStatic<T>` (similar for `&mut`).
/// 2. Implement [`Tagged`] on the type.
///
/// Both methods can be used, but they will not count as the same type
/// to [`AnythingExt`] even though they name the same value.
///
/// This wrapper is different to the [`Static`](crate::tag::Static) type in the `tag` module.
/// `Static` will reify to the given `T`. This is good for the provide API, but
/// for `Anything` this doesn't work because it requires that the type reifies to itself.
/// This wrapper implements this.
///
/// ## Invariants
///
/// This type is `repr(transparent)` for `T` so may be transmuted to/from.
///
/// # Examples
///
/// ```
/// use supply::prelude::*;
///
/// struct MyType(i32);
///
/// let a: &dyn Anything = AnyStatic::from_ref(&MyType(42));
///
/// let x = a.downcast_ref::<AnyStatic<MyType>>();
/// assert_eq!(x.unwrap().0, 42);
/// ```
#[repr(transparent)]
pub struct AnyStatic<T: ?Sized>(T);

impl<T: ?Sized> AnyStatic<T> {
    /// Create a `AnyStatic<T>`.
    pub fn new(value: T) -> Self
    where
        T: Sized,
    {
        Self(value)
    }

    /// Convert a `&T` into a `&AnyStatic<T>`.
    ///
    /// # Examples
    ///
    /// ```
    /// use supply::prelude::*;
    ///
    /// struct MyType;
    ///
    /// let x: &AnyStatic<MyType> = AnyStatic::from_ref(&MyType);
    /// let _y: &MyType = x;
    /// ```
    pub fn from_ref(value: &T) -> &Self {
        unsafe { &*(value as *const T as *const Self) }
    }

    /// Convert a `&mut T` into a `&mut AnyStatic<T>`.
    ///
    /// ```
    /// use supply::prelude::*;
    ///
    /// struct MyType;
    ///
    /// let mut a = MyType;
    ///
    /// let x: &mut AnyStatic<MyType> = AnyStatic::from_mut(&mut a);
    /// let _y: &mut MyType = x;
    /// ```
    pub fn from_mut(value: &mut T) -> &mut Self {
        unsafe { &mut *(value as *mut T as *mut Self) }
    }

    /// Get the inner `T`.
    ///
    /// ```
    /// use supply::prelude::*;
    ///
    /// let x: AnyStatic<i32> = AnyStatic::new(123);
    /// assert_eq!(x.into_inner(), 123);
    /// ```
    pub fn into_inner(self) -> T
    where
        T: Sized,
    {
        self.0
    }
}

impl<T: ?Sized> core::ops::Deref for AnyStatic<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T: ?Sized> core::ops::DerefMut for AnyStatic<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

impl<T: ?Sized + 'static> WithLt<Lt0> for AnyStatic<T> {
    type Reified = AnyStatic<T>;
}

impl<T: ?Sized + 'static> Tagged for AnyStatic<T> {
    type Tag = Self;
}

impl<T: ?Sized + 'static> Tag for AnyStatic<T> {
    type LifetimesTag = lt_structure![];
}