maybe-owned 0.3.4

//! This crate only provides the `MaybeOwned` and `MaybeOwnedMut` enums
//!
//! Take a look at their documentation for more information.
//!
#![warn(missing_docs)]
#[cfg(feature = "serde")]
extern crate serde;

#[cfg(feature = "serde")]
mod serde_impls;

mod transitive_impl;

use std::borrow::{Borrow, BorrowMut, Cow};
use std::cmp::Ordering;
use std::fmt;
use std::hash::{Hash, Hasher};
use std::ops::{Deref, DerefMut};
use std::str::FromStr;

/// This type provides a way to store data to which you either have a
/// reference to or which you do own.
///
/// It provides `From<T>`, `From<&'a T>` implementations and, in difference
/// to `Cow` does _not_ require `ToOwned` to be implemented which makes it
/// compatible with non cloneable data, as a draw back of this it does not
/// know about `ToOwned`. As a consequence of it can't know that `&str` should
/// be the borrowed version of `String` and not `&String` this is especially
/// bad wrt. `Box` as the borrowed version of `Box<T>` would be `&Box<T>`.
///
/// While this crate has some drawbacks compared to `Cow` is has the benefit,
/// that it works with Types which neither implement `Clone` nor `ToOwned`.
/// Another benefit lies in the ability to write API functions which accept
/// a generic parameter `E: Into<MaybeOwned<'a, T>>` as the API consumer can
/// pass `T`, `&'a T` and `MaybeOwned<'a, T>` as argument, without requiring
/// a explicit `Cow::Owned` or a split into two functions one accepting
/// owed and the other borrowed values.
///
/// # Alternatives
///
/// If you mainly have values implementing `ToOwned` like `&str`/`String`, `Path`/`PathBuf` or
/// `&[T]`/`Vec<T>` using `std::borrow::Cow` might be preferable.
///
/// If you want to be able to treat `&T`, `&mut T`, `Box<T>` and `Arc<T>` the same
/// consider using [`reffers::rbma::RBMA`](https://docs.rs/reffers)
/// (through not all types/platforms are supported because
/// as it relies on the fact that for many pointers the lowest two bits are 0, and stores
/// the discriminant in them, nevertheless this is can only be used with 32bit-aligned data,
/// e.g. using a &u8 _might_ fail). RBMA also allows you to recover a `&mut T` if it was created
/// from `Box<T>`, `&mut T` or a unique `Arc`.
///
///
/// # Examples
///
/// ```
/// # use maybe_owned::MaybeOwned;
/// struct PseudoBigData(u8);
/// fn pseudo_register_fn<'a, E>(_val: E) where E: Into<MaybeOwned<'a, PseudoBigData>> { }
///
/// let data = PseudoBigData(12);
/// let data2 = PseudoBigData(13);
///
/// pseudo_register_fn(&data);
/// pseudo_register_fn(&data);
/// pseudo_register_fn(data2);
/// pseudo_register_fn(MaybeOwned::Owned(PseudoBigData(111)));
/// ```
///
/// ```
/// # use maybe_owned::MaybeOwned;
/// #[repr(C)]
/// struct OpaqueFFI {
///     ref1:  * const u8
///     //we also might want to have PhantomData etc.
/// }
///
/// // does not work as it does not implement `ToOwned`
/// // let _ = Cow::Owned(OpaqueFFI { ref1: 0 as *const u8});
///
/// // ok, MaybeOwned can do this (but can't do &str<->String as tread of)
/// let _ = MaybeOwned::Owned(OpaqueFFI { ref1: 0 as *const u8 });
/// ```
///
/// ```
/// # #[macro_use]
/// # extern crate serde_derive;
/// # extern crate serde_json;
/// # extern crate maybe_owned;
/// # #[cfg(feature = "serde")]
/// # fn main() {
/// # use maybe_owned::MaybeOwned;
/// use std::collections::HashMap;
///
/// #[derive(Serialize, Deserialize)]
/// struct SerializedData<'a> {
///     data: MaybeOwned<'a, HashMap<String, i32>>,
/// }
///
/// let mut map = HashMap::new();
/// map.insert("answer".to_owned(), 42);
///
/// // serializing can use borrowed data to avoid unnecessary copying
/// let bytes = serde_json::to_vec(&SerializedData { data: (&map).into() }).unwrap();
///
/// // deserializing creates owned data
/// let deserialized: SerializedData = serde_json::from_slice(&bytes).unwrap();
/// assert_eq!(deserialized.data["answer"], 42);
/// # }
/// # #[cfg(not(feature = "serde"))] fn main() {}
/// ```
///
/// # Transitive `std::ops` implementations
///
/// There are transitive implementations for most operator in `std::ops`.
///
/// A Op between a `MaybeOwned<L>` and `MaybeOwned<R>` is implemented if:
///
/// - L impl the Op with R
/// - L impl the Op with &R
/// - &L impl the Op with R
/// - &L impl the Op with &R
/// - the `Output` of all aboves implementations is
///   the same type
///
///
/// The `Neg` (`-` prefix) op is implemented for `V` if:
///
/// - `V` impl `Neg`
/// - `&V` impl `Neg`
/// - both have the same `Output`
///
///
/// The `Not` (`!` prefix) op is implemented for `V` if:
///
/// - `V` impl `Not`
/// - `&V` impl `Not`
/// - both have the same `Output`
///
/// Adding implementations for Ops which add a `MaybeOwned` to
/// a non `MaybeOwned` value (like `MaybeOwned<T> + T`) requires
/// far reaching specialization in rust and is therefore not done
/// for now.
#[derive(Debug)]
pub enum MaybeOwned<'a, T: 'a> {
    /// owns T
    Owned(T),
    /// has a reference to T
    Borrowed(&'a T),
}

/// This type is basically the same as `MaybeOwned`,
/// but works with mutable references.
///
/// Note that while you can se `MaybeOwned` as a alternative
/// implementation for a Cow (Copy-On-Write) type this isn't
/// really the case for `MaybeOwnedMut` as changing it will
/// potentially change the source through the given `&mut`
/// reference. For example the transitive add assign (+=)
/// implementation for `MaybeOwned` does (need to) convert
/// the given instance into a owned variant before using
/// `+=` on the contained type. But for `MaybeOwnedMut` it
/// can directly use `+=` on the `&mut` contained in the
/// `Borrowed` variant!
#[derive(Debug)]
pub enum MaybeOwnedMut<'a, T: 'a> {
    /// owns T
    Owned(T),
    /// has a reference to T
    Borrowed(&'a mut T),
}

macro_rules! common_impls {
    ($Name:ident) => {
        impl<T> $Name<'_, T> {
            /// Returns true if the data is owned else false.
            pub fn is_owned(&self) -> bool {
                match self {
                    Self::Owned(_) => true,
                    Self::Borrowed(_) => false,
                }
            }
        }

        impl<T: Clone> $Name<'_, T> {

            /// Return the contained data in it's owned form.
            ///
            /// If it's borrowed this will clone it.
            pub fn into_owned(self) -> T {
                match self {
                    Self::Owned(v) => v,
                    Self::Borrowed(v) => v.clone(),
                }
            }

            /// Internally converts the type into it's owned variant.
            ///
            /// Conversion from a reference to the owned variant is done by cloning.
            ///
            /// *This returns a `&mut T` and as such can be used to "unconditionally"
            ///  get an `&mut T`*. Be aware that while this works with both `MaybeOwned`
            ///  and `MaybeOwnedMut` it also converts it to an owned variant in both
            ///  cases. So while it's the best way to get a `&mut T` for `MaybeOwned`
            ///  for `MaybeOwnedMut` it's preferable to use `as_mut` from `AsMut`.
            ///
            /// ## Example
            ///
            /// ```
            /// use maybe_owned::MaybeOwned;
            ///
            /// #[derive(Clone, Debug, PartialEq, Eq)]
            /// struct PseudoBigData(u8);
            ///
            /// let data = PseudoBigData(12);
            ///
            /// let mut maybe: MaybeOwned<PseudoBigData> = (&data).into();
            /// assert_eq!(false, maybe.is_owned());
            ///
            /// {
            ///     let reference = maybe.make_owned();
            ///     assert_eq!(&mut PseudoBigData(12), reference);
            /// }
            /// assert!(maybe.is_owned());
            /// ```
            pub fn make_owned(&mut self) -> &mut T {
                match self {
                    Self::Owned(v) => v,
                    Self::Borrowed(v) => {
                        *self = Self::Owned(v.clone());
                        match self {
                            Self::Owned(v) => v,
                            Self::Borrowed(..) => unreachable!(),
                        }
                    }
                }
            }
        }

        impl<T> Deref for $Name<'_, T> {
            type Target = T;

            fn deref(&self) -> &T {
                match self {
                    Self::Owned(v) => v,
                    Self::Borrowed(v) => v,
                }
            }
        }

        impl<T> AsRef<T> for $Name<'_, T> {
            fn as_ref(&self) -> &T {
                self
            }
        }

        impl<T> From<T> for $Name<'_, T> {
            fn from(v: T) -> Self {
                Self::Owned(v)
            }
        }

        impl<T> Borrow<T> for $Name<'_, T> {
            fn borrow(&self) -> &T {
                self
            }
        }

        impl<T: Default> Default for $Name<'_, T> {
            fn default() -> Self {
                Self::Owned(T::default())
            }
        }

        impl<'b, A: PartialEq<B>, B> PartialEq<$Name<'b, B>> for $Name<'_, A> {
            #[inline]
            fn eq(&self, other: &$Name<'b, B>) -> bool {
                PartialEq::eq(self.deref(), other.deref())
            }
        }

        impl<'a, T: Eq> Eq for $Name<'a, T> {}

        impl<T: FromStr> FromStr for $Name<'_, T> {
            type Err = T::Err;

            fn from_str(s: &str) -> Result<Self, Self::Err> {
                Ok(Self::Owned(T::from_str(s)?))
            }
        }

        // TODO: Specify RHS
        impl<T: PartialOrd> PartialOrd for $Name<'_, T> {
            #[inline]
            fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
                PartialOrd::partial_cmp(self.deref(), other.deref())
            }
        }

        impl<T: Ord> Ord for $Name<'_, T> {
            #[inline]
            fn cmp(&self, other: &Self) -> Ordering {
                Ord::cmp(self.deref(), other.deref())
            }
        }

        impl<T: Hash> Hash for $Name<'_, T> {
            #[inline]
            fn hash<H: Hasher>(&self, state: &mut H) {
                Hash::hash(self.deref(), state)
            }
        }

        impl<'a, T: fmt::Display> fmt::Display for $Name<'a, T> {
            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                match self {
                    Self::Owned(o) => fmt::Display::fmt(o, f),
                    Self::Borrowed(b) => fmt::Display::fmt(b, f),
                }
            }
        }
    };
}

common_impls!(MaybeOwned);
common_impls!(MaybeOwnedMut);

impl<'a, T> From<&'a T> for MaybeOwned<'a, T> {
    fn from(v: &'a T) -> Self {
        Self::Borrowed(v)
    }
}

impl<'a, T> From<&'a mut T> for MaybeOwnedMut<'a, T> {
    fn from(v: &'a mut T) -> Self {
        Self::Borrowed(v)
    }
}

impl<'a, T: ToOwned<Owned = T>> From<Cow<'a, T>> for MaybeOwned<'a, T> {
    fn from(cow: Cow<'a, T>) -> MaybeOwned<'a, T> {
        match cow {
            Cow::Owned(v) => MaybeOwned::Owned(v),
            Cow::Borrowed(v) => MaybeOwned::Borrowed(v),
        }
    }
}

impl<'a, T: ToOwned<Owned = T>> Into<Cow<'a, T>> for MaybeOwned<'a, T> {
    fn into(self) -> Cow<'a, T> {
        match self {
            MaybeOwned::Owned(v) => Cow::Owned(v),
            MaybeOwned::Borrowed(v) => Cow::Borrowed(v),
        }
    }
}

impl<T: Clone> Clone for MaybeOwned<'_, T> {
    fn clone(&self) -> Self {
        match self {
            Self::Owned(v) => Self::Owned(v.clone()),
            Self::Borrowed(v) => Self::Borrowed(v),
        }
    }
}

impl<T> MaybeOwned<'_, T> {
    /// Returns a `&mut` if possible.
    ///
    /// If the internal representation is borrowed (`&T`) then
    /// this method will return `None`
    pub fn as_mut(&mut self) -> Option<&mut T> {
        match self {
            MaybeOwned::Owned(value) => Some(value),
            MaybeOwned::Borrowed(_) => None
        }
    }
}

impl<T: Clone> MaybeOwned<'_, T> {
    /// Acquires a mutable reference to owned data.
    ///
    /// Clones data if it is not already owned.
    ///
    /// ## Example
    ///
    /// ```
    /// use maybe_owned::MaybeOwned;
    ///
    /// #[derive(Clone, Debug, PartialEq, Eq)]
    /// struct PseudoBigData(u8);
    ///
    /// let data = PseudoBigData(12);
    ///
    /// let mut maybe: MaybeOwned<PseudoBigData> = (&data).into();
    /// assert_eq!(false, maybe.is_owned());
    ///
    /// {
    ///     let reference = maybe.to_mut();
    ///     assert_eq!(&mut PseudoBigData(12), reference);
    /// }
    /// assert!(maybe.is_owned());
    /// ```
    ///
    #[deprecated = "use `make_owned` instead"]
    pub fn to_mut(&mut self) -> &mut T {
        match *self {
            Self::Owned(ref mut v) => v,
            Self::Borrowed(v) => {
                *self = Self::Owned(v.clone());
                match *self {
                    Self::Owned(ref mut v) => v,
                    Self::Borrowed(..) => unreachable!(),
                }
            }
        }
    }
}

impl<T> DerefMut for MaybeOwnedMut<'_, T> {
    fn deref_mut(&mut self) -> &mut T {
        match self {
            Self::Owned(v) => v,
            Self::Borrowed(v) => v,
        }
    }
}

impl<T> AsMut<T> for MaybeOwnedMut<'_, T> {
    fn as_mut(&mut self) -> &mut T {
        match self {
            Self::Owned(v) => v,
            Self::Borrowed(v) => v,
        }
    }
}

impl<T> BorrowMut<T> for MaybeOwnedMut<'_, T> {
    fn borrow_mut(&mut self) -> &mut T {
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    type TestType = Vec<()>;

    fn with_into<'a, I: Into<MaybeOwned<'a, TestType>>>(v: I) -> MaybeOwned<'a, TestType> {
        v.into()
    }

    #[test]
    fn is_owned() {
        let data = TestType::default();
        assert!(MaybeOwned::Owned(data).is_owned());
    }

    #[test]
    fn make_owned() {
        let mut a = MaybeOwned::Borrowed(&12u8);
        assert!(!a.is_owned());
        a.make_owned();
        assert!(a.is_owned());
        assert_eq!(&*a, &12);
    }

    #[test]
    fn into_with_owned() {
        //ty check if it accepts references
        let data = TestType::default();
        assert!(with_into(data).is_owned())
    }
    #[test]
    fn into_with_borrow() {
        //ty check if it accepts references
        let data = TestType::default();
        assert!(!with_into(&data).is_owned());
    }

    #[test]
    fn clone_owned() {
        let maybe = MaybeOwned::<TestType>::default();
        assert!(maybe.clone().is_owned());
    }

    #[test]
    fn clone_borrow() {
        let data = TestType::default();
        let maybe: MaybeOwned<TestType> = (&data).into();
        assert!(!maybe.clone().is_owned());
    }

    #[test]
    fn to_mut() {
        let data = TestType::default();
        let mut maybe: MaybeOwned<TestType> = (&data).into();
        assert!(!maybe.is_owned());
        {
            #[allow(deprecated)]
            let _mut_ref = maybe.to_mut();
        }
        assert!(maybe.is_owned());
    }

    #[test]
    fn into_inner() {
        let data = vec![1u32, 2];
        let maybe: MaybeOwned<Vec<u32>> = (&data).into();
        assert_eq!(data, maybe.into_owned());
    }

    #[test]
    fn has_default() {
        #[derive(Default)]
        struct TestType(u8);
        let _x: MaybeOwned<TestType> = Default::default();
    }

    #[test]
    fn has_clone() {
        #[derive(Clone)]
        struct TestType(u8);
        let _x = TestType(12).clone();
    }

    #[test]
    fn has_deref() {
        let a = MaybeOwned::Owned(vec![1u8]);
        let _ = a.len();

        let a = MaybeOwnedMut::Owned(vec![1u8]);
        let _ = a.len();
    }

    #[test]
    fn has_deref_mut() {
        let mut a = MaybeOwnedMut::Owned(vec![1u8]);
        a[0] = 12u8;
    }

    #[test]
    fn has_partial_eq() {
        #[derive(PartialEq)]
        struct TestType(f32);

        let n = TestType(33.0);
        let a = MaybeOwned::Owned(TestType(42.0));
        let b = MaybeOwned::Borrowed(&n);
        let c = MaybeOwned::Owned(TestType(33.0));

        assert_eq!(a == b, false);
        assert_eq!(b == c, true);
        assert_eq!(c == a, false);
    }

    #[test]
    fn has_eq() {
        #[derive(PartialEq, Eq)]
        struct TestType(i32);

        let n = TestType(33);
        let a = MaybeOwned::Owned(TestType(42));
        let b = MaybeOwned::Borrowed(&n);
        let c = MaybeOwned::Owned(TestType(33));

        assert_eq!(a == b, false);
        assert_eq!(b == c, true);
        assert_eq!(c == a, false);
    }

    #[test]
    fn has_partial_ord() {
        #[derive(PartialEq, PartialOrd)]
        struct TestType(f32);

        let n = TestType(33.0);
        let a = MaybeOwned::Owned(TestType(42.0));
        let b = MaybeOwned::Borrowed(&n);
        let c = MaybeOwned::Owned(TestType(33.0));

        assert_eq!(a > b, true);
        assert_eq!(b > c, false);
        assert_eq!(a < c, false);
    }

    #[test]
    fn has_ord() {
        #[derive(PartialEq, Eq, PartialOrd, Ord)]
        struct TestType(i32);

        let n = TestType(33);
        let a = MaybeOwned::Owned(TestType(42));
        let b = MaybeOwned::Borrowed(&n);
        let c = MaybeOwned::Owned(TestType(33));

        assert_eq!(a > b, true);
        assert_eq!(b > c, false);
        assert_eq!(a < c, false);
    }

    #[test]
    fn has_hash() {
        use std::collections::HashMap;

        let mut map = HashMap::new();
        map.insert(MaybeOwned::Owned(42), 33);

        assert_eq!(map.get(&MaybeOwned::Borrowed(&42)), Some(&33));
    }

    #[test]
    fn has_borrow() {
        let v = MaybeOwned::Owned(42);
        let _ = Borrow::<u8>::borrow(&v);

        let v = MaybeOwnedMut::Owned(42);
        let _ = Borrow::<u8>::borrow(&v);
    }

    #[test]
    fn has_borrow_mut() {
        let mut v = MaybeOwnedMut::Owned(42);
        let _ = BorrowMut::<u8>::borrow_mut(&mut v);
    }

    #[test]
    fn has_as_ref() {
        let v = MaybeOwned::Owned(42);
        let _ = AsRef::<u8>::borrow(&v);

        let v = MaybeOwnedMut::Owned(42);
        let _ = AsRef::<u8>::borrow(&v);
    }

    #[test]
    fn has_as_mut() {
        // uses a as_mut method
        let mut v: MaybeOwned<u8> = (&11).into();
        assert_eq!(v.as_mut(), None);

        let mut v: MaybeOwned<u8> = 12.into();
        assert_eq!(v.as_mut(), Some(&mut 12));

        // uses AsMut
        let mut v = MaybeOwnedMut::Owned(42);
        let _ = AsMut::<u8>::borrow_mut(&mut v);
    }

    #[test]
    fn has_display() {
        let n = 33;
        let a = MaybeOwned::Owned(42);
        let b = MaybeOwned::Borrowed(&n);

        let s = format!("{} {}", a, b);

        assert_eq!(s, "42 33");
    }

    #[test]
    fn from_cow() {
        use std::borrow::Cow;

        fn test<'a, V: Into<MaybeOwned<'a, i32>>>(v: V, n: i32) {
            assert_eq!(*v.into(), n)
        }

        let n = 33;
        test(Cow::Owned(42), 42);
        test(Cow::Borrowed(&n), n);
    }

    #[test]
    fn into_cow() {
        use std::borrow::Cow;

        fn test<'a, V: Into<Cow<'a, i32>>>(v: V, n: i32) {
            assert_eq!(*v.into(), n)
        }

        let n = 33;
        test(MaybeOwned::Owned(42), 42);
        test(MaybeOwned::Borrowed(&n), n);
    }

    #[test]
    fn from_str() {
        let as_string = "12";
        //assumption as_string is convertable to u32
        assert_eq!(12u32, as_string.parse().unwrap());
        assert_eq!(MaybeOwned::Owned(12u32), as_string.parse().unwrap());
    }

    #[test]
    fn as_ref() {
        let data = TestType::default();
        let maybe_owned = MaybeOwned::Borrowed(&data);
        let _ref: &TestType = maybe_owned.as_ref();
        assert_eq!(&data as *const _ as usize, _ref as *const _ as usize);
    }

    #[test]
    fn borrow() {
        use std::borrow::Borrow;

        let data = TestType::default();
        let maybe_owned = MaybeOwned::Borrowed(&data);
        let _ref: &TestType = maybe_owned.borrow();
        assert_eq!(&data as *const _ as usize, _ref as *const _ as usize);
    }

    #[test]
    fn reborrow_mut() {
        let value = vec![0u32];
        let mut value = MaybeOwnedMut::Owned(value);
        let mut reborrow = MaybeOwnedMut::Borrowed(value.deref_mut());
        reborrow.push(1);
        assert_eq!(&[0, 1], &value[..]);
    }
}