//! **Development in progress**
//!
//! This crate provides a trait [`AsIs`], an enum [`Is<'a, T>`], and variants of them.
//!
//! [`AsIs`]: trait.AsIs.html
//! [`Is<'a, T>`]: enum.Is.html

#![no_std]

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(feature = "alloc")]
use alloc::borrow::Cow;

mod to_owned;
pub use to_owned::ToOwned;

mod is;
mod is_cow;
mod is_mut;

pub mod ops;
pub mod ref_ops;

pub use is::Is;
pub use is_cow::IsCow;
pub use is_mut::IsMut;

mod foreign;
pub use foreign::{StringStub, VecStub};

#[cfg(test)]
mod tests;

use core::borrow::{Borrow, BorrowMut};

/// Used to do a cheap conversion into [`Is<'a, T>`] in a generic context.
///
/// [`Is<'a, T>`]: enum.Is.html
pub trait AsIs: Sized + Borrow<Self::Is> {
    /// The base type associated with both owned and borrowed data.
    type Is: ?Sized + ToOwned;

    /// Converts `self` into an [`Is<'a, Self::Is>`].
    ///
    /// [`Is<'a, Self::Is>`]: enum.Is.html
    #[allow(clippy::wrong_self_convention)]
    fn as_is<'a>(self) -> Is<'a, Self::Is>
    where
        Self: 'a;

    /// Immutably borrows from `self` by default, but can be overridden to clone `self` if
    /// appropriate.
    fn borrow_or_clone<B: ?Sized>(&self) -> IsCow<'_, B>
    where
        Self::Is: Borrow<B>,
        Owned<Self>: Borrow<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        IsCow::Borrowed(self.borrow().borrow())
    }

    /// Converts `self` into an [`Is<'a, B>`].
    ///
    /// [`Is<'a, B>`]: enum.Is.html
    fn into_is<'a, B: ?Sized>(self) -> Is<'a, B>
    where
        Self: 'a,
        Self::Is: BorrowMut<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        match self.as_is() {
            Is::Owned(x) => Is::Owned(x),
            Is::Borrowed(x) => Is::Borrowed(x.borrow()),
            Is::MutBorrowed(x) => Is::MutBorrowed(x.borrow_mut()),
        }
    }

    /// Converts `self` into an [`IsCow<'a, B>`].
    ///
    /// [`IsCow<'a, B>`]: enum.IsCow.html
    fn into_is_cow<'a, B: ?Sized>(self) -> IsCow<'a, B>
    where
        Self: 'a,
        Self::Is: Borrow<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        match self.as_is() {
            Is::Owned(x) => IsCow::Owned(x),
            Is::Borrowed(x) => IsCow::Borrowed(x.borrow()),
            Is::MutBorrowed(x) => IsCow::Borrowed((*x).borrow()),
        }
    }

    /// Converts `self` into an [`IsMut<'a, B>`] without cloning if possible.
    ///
    /// # Errors
    ///
    /// If `self` cannot be converted without cloning, returns `self` as is.
    ///
    /// [`IsMut<'a, B>`]: enum.IsMut.html
    fn try_into_is_mut<'a, B: ?Sized>(self) -> Result<IsMut<'a, B>, Is<'a, Self::Is>>
    where
        Self: 'a,
        Self::Is: BorrowMut<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        match self.as_is() {
            Is::Owned(x) => Ok(IsMut::Owned(x)),
            Is::Borrowed(x) => Err(Is::Borrowed(x)),
            Is::MutBorrowed(x) => Ok(IsMut::MutBorrowed(x.borrow_mut())),
        }
    }

    /// Converts `self` into an owned data without cloning if possible.
    ///
    /// # Errors
    ///
    /// If `self` cannot be converted without cloning, returns `self` as is.
    fn try_into_owned<'a>(self) -> Result<Owned<Self>, Is<'a, Self::Is>>
    where
        Self: 'a,
    {
        match self.as_is() {
            Is::Owned(x) => Ok(x),
            Is::Borrowed(x) => Err(Is::Borrowed(x)),
            Is::MutBorrowed(x) => Err(Is::MutBorrowed(x)),
        }
    }

    /// Converts `self` into a [`Cow<'a, B>`]. Only available if the `alloc` feature
    /// is enabled.
    ///
    /// [`Cow<'a, B>`]: https://doc.rust-lang.org/alloc/borrow/enum.Cow.html
    #[cfg(feature = "alloc")]
    fn into_cow<'a, B: ?Sized>(self) -> Cow<'a, B>
    where
        Self: 'a,
        Self::Is: Borrow<B>,
        B: ToOwned<Owned = Owned<Self>> + alloc::borrow::ToOwned<Owned = Owned<Self>>,
    {
        match self.as_is() {
            Is::Owned(x) => Cow::Owned(x),
            Is::Borrowed(x) => Cow::Borrowed(x.borrow()),
            Is::MutBorrowed(x) => Cow::Borrowed((*x).borrow()),
        }
    }
}

/// Used to do a cheap conversion into [`IsMut<'a, T>`] in a generic context.
///
/// [`IsMut<'a, T>`]: enum.IsMut.html
pub trait AsIsMut: AsIs + BorrowMut<Self::Is> {
    /// Converts `self` into an [`IsMut<'a, Self::Is>`].
    ///
    /// [`IsMut<'a, Self::Is>`]: enum.IsMut.html
    #[allow(clippy::wrong_self_convention)]
    fn as_is_mut<'a>(self) -> IsMut<'a, Self::Is>
    where
        Self: 'a;

    /// Mutably borrows from `self` by default, but clones `self` if [`self.borrow_or_clone()`] is overridden to clone `self`.
    ///
    /// [`self.borrow_or_clone()`]: trait.AsIs.html#method.borrow_or_clone
    fn borrow_mut_or_clone<B: ?Sized>(&mut self) -> IsMut<'_, B>
    where
        Self::Is: BorrowMut<B>,
        Owned<Self>: BorrowMut<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        match self.borrow_or_clone() {
            IsCow::Owned(x) => IsMut::Owned(x),
            IsCow::Borrowed(_) => IsMut::MutBorrowed(self.borrow_mut().borrow_mut()),
        }
    }

    /// Converts `self` into an [`IsMut<'a, B>`].
    ///
    /// [`IsMut<'a, B>`]: enum.IsMut.html
    fn into_is_mut<'a, B: ?Sized>(self) -> IsMut<'a, B>
    where
        Self: 'a,
        Self::Is: BorrowMut<B>,
        B: ToOwned<Owned = Owned<Self>>,
    {
        match self.as_is_mut() {
            IsMut::Owned(x) => IsMut::Owned(x),
            IsMut::MutBorrowed(x) => IsMut::MutBorrowed(x.borrow_mut()),
        }
    }
}

/// The owned type associated with a type.
pub type Owned<T> = <<T as AsIs>::Is as ToOwned>::Owned;

impl<T: ?Sized + ToOwned> AsIs for &T {
    type Is = T;

    fn as_is<'a>(self) -> Is<'a, Self::Is>
    where
        Self: 'a,
    {
        Is::Borrowed(self)
    }
}

impl<T: ?Sized + ToOwned> AsIs for &mut T {
    type Is = T;

    fn as_is<'a>(self) -> Is<'a, Self::Is>
    where
        Self: 'a,
    {
        Is::MutBorrowed(self)
    }
}

impl<T: ?Sized + ToOwned> AsIsMut for &mut T {
    fn as_is_mut<'a>(self) -> IsMut<'a, Self::Is>
    where
        Self: 'a,
    {
        IsMut::MutBorrowed(self)
    }
}