/rust/registry/src/index.crates.io-1949cf8c6b5b557f/maybe-owned-0.3.4/src/lib.rs

Source
//! 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[..]);
    }
}

Coverage Report

Created: 2026-02-26 06:24

Line	Count	Source
1		//! This crate only provides the `MaybeOwned` and `MaybeOwnedMut` enums
2		//!
3		//! Take a look at their documentation for more information.
4		//!
5		#![warn(missing_docs)]
6		#[cfg(feature = "serde")]
7		extern crate serde;
8
9		#[cfg(feature = "serde")]
10		mod serde_impls;
11
12		mod transitive_impl;
13
14		use std::borrow::{Borrow, BorrowMut, Cow};
15		use std::cmp::Ordering;
16		use std::fmt;
17		use std::hash::{Hash, Hasher};
18		use std::ops::{Deref, DerefMut};
19		use std::str::FromStr;
20
21		/// This type provides a way to store data to which you either have a
22		/// reference to or which you do own.
23		///
24		/// It provides `From<T>`, `From<&'a T>` implementations and, in difference
25		/// to `Cow` does _not_ require `ToOwned` to be implemented which makes it
26		/// compatible with non cloneable data, as a draw back of this it does not
27		/// know about `ToOwned`. As a consequence of it can't know that `&str` should
28		/// be the borrowed version of `String` and not `&String` this is especially
29		/// bad wrt. `Box` as the borrowed version of `Box<T>` would be `&Box<T>`.
30		///
31		/// While this crate has some drawbacks compared to `Cow` is has the benefit,
32		/// that it works with Types which neither implement `Clone` nor `ToOwned`.
33		/// Another benefit lies in the ability to write API functions which accept
34		/// a generic parameter `E: Into<MaybeOwned<'a, T>>` as the API consumer can
35		/// pass `T`, `&'a T` and `MaybeOwned<'a, T>` as argument, without requiring
36		/// a explicit `Cow::Owned` or a split into two functions one accepting
37		/// owed and the other borrowed values.
38		///
39		/// # Alternatives
40		///
41		/// If you mainly have values implementing `ToOwned` like `&str`/`String`, `Path`/`PathBuf` or
42		/// `&[T]`/`Vec<T>` using `std::borrow::Cow` might be preferable.
43		///
44		/// If you want to be able to treat `&T`, `&mut T`, `Box<T>` and `Arc<T>` the same
45		/// consider using [`reffers::rbma::RBMA`](https://docs.rs/reffers)
46		/// (through not all types/platforms are supported because
47		/// as it relies on the fact that for many pointers the lowest two bits are 0, and stores
48		/// the discriminant in them, nevertheless this is can only be used with 32bit-aligned data,
49		/// e.g. using a &u8 _might_ fail). RBMA also allows you to recover a `&mut T` if it was created
50		/// from `Box<T>`, `&mut T` or a unique `Arc`.
51		///
52		///
53		/// # Examples
54		///
55		/// ```
56		/// # use maybe_owned::MaybeOwned;
57		/// struct PseudoBigData(u8);
58		/// fn pseudo_register_fn<'a, E>(_val: E) where E: Into<MaybeOwned<'a, PseudoBigData>> { }
59		///
60		/// let data = PseudoBigData(12);
61		/// let data2 = PseudoBigData(13);
62		///
63		/// pseudo_register_fn(&data);
64		/// pseudo_register_fn(&data);
65		/// pseudo_register_fn(data2);
66		/// pseudo_register_fn(MaybeOwned::Owned(PseudoBigData(111)));
67		/// ```
68		///
69		/// ```
70		/// # use maybe_owned::MaybeOwned;
71		/// #[repr(C)]
72		/// struct OpaqueFFI {
73		/// ref1: * const u8
74		/// //we also might want to have PhantomData etc.
75		/// }
76		///
77		/// // does not work as it does not implement `ToOwned`
78		/// // let _ = Cow::Owned(OpaqueFFI { ref1: 0 as *const u8});
79		///
80		/// // ok, MaybeOwned can do this (but can't do &str<->String as tread of)
81		/// let _ = MaybeOwned::Owned(OpaqueFFI { ref1: 0 as *const u8 });
82		/// ```
83		///
84		/// ```
85		/// # #[macro_use]
86		/// # extern crate serde_derive;
87		/// # extern crate serde_json;
88		/// # extern crate maybe_owned;
89		/// # #[cfg(feature = "serde")]
90		/// # fn main() {
91		/// # use maybe_owned::MaybeOwned;
92		/// use std::collections::HashMap;
93		///
94		/// #[derive(Serialize, Deserialize)]
95		/// struct SerializedData<'a> {
96		/// data: MaybeOwned<'a, HashMap<String, i32>>,
97		/// }
98		///
99		/// let mut map = HashMap::new();
100		/// map.insert("answer".to_owned(), 42);
101		///
102		/// // serializing can use borrowed data to avoid unnecessary copying
103		/// let bytes = serde_json::to_vec(&SerializedData { data: (&map).into() }).unwrap();
104		///
105		/// // deserializing creates owned data
106		/// let deserialized: SerializedData = serde_json::from_slice(&bytes).unwrap();
107		/// assert_eq!(deserialized.data["answer"], 42);
108		/// # }
109		/// # #[cfg(not(feature = "serde"))] fn main() {}
110		/// ```
111		///
112		/// # Transitive `std::ops` implementations
113		///
114		/// There are transitive implementations for most operator in `std::ops`.
115		///
116		/// A Op between a `MaybeOwned<L>` and `MaybeOwned<R>` is implemented if:
117		///
118		/// - L impl the Op with R
119		/// - L impl the Op with &R
120		/// - &L impl the Op with R
121		/// - &L impl the Op with &R
122		/// - the `Output` of all aboves implementations is
123		/// the same type
124		///
125		///
126		/// The `Neg` (`-` prefix) op is implemented for `V` if:
127		///
128		/// - `V` impl `Neg`
129		/// - `&V` impl `Neg`
130		/// - both have the same `Output`
131		///
132		///
133		/// The `Not` (`!` prefix) op is implemented for `V` if:
134		///
135		/// - `V` impl `Not`
136		/// - `&V` impl `Not`
137		/// - both have the same `Output`
138		///
139		/// Adding implementations for Ops which add a `MaybeOwned` to
140		/// a non `MaybeOwned` value (like `MaybeOwned<T> + T`) requires
141		/// far reaching specialization in rust and is therefore not done
142		/// for now.
143		#[derive(Debug)]
144		pub enum MaybeOwned<'a, T: 'a> {
145		/// owns T
146		Owned(T),
147		/// has a reference to T
148		Borrowed(&'a T),
149		}
150
151		/// This type is basically the same as `MaybeOwned`,
152		/// but works with mutable references.
153		///
154		/// Note that while you can se `MaybeOwned` as a alternative
155		/// implementation for a Cow (Copy-On-Write) type this isn't
156		/// really the case for `MaybeOwnedMut` as changing it will
157		/// potentially change the source through the given `&mut`
158		/// reference. For example the transitive add assign (+=)
159		/// implementation for `MaybeOwned` does (need to) convert
160		/// the given instance into a owned variant before using
161		/// `+=` on the contained type. But for `MaybeOwnedMut` it
162		/// can directly use `+=` on the `&mut` contained in the
163		/// `Borrowed` variant!
164		#[derive(Debug)]
165		pub enum MaybeOwnedMut<'a, T: 'a> {
166		/// owns T
167		Owned(T),
168		/// has a reference to T
169		Borrowed(&'a mut T),
170		}
171
172		macro_rules! common_impls {
173		($Name:ident) => {
174		impl<T> $Name<'_, T> {
175		/// Returns true if the data is owned else false.
176		pub fn is_owned(&self) -> bool {
177		match self {
178		Self::Owned(_) => true,
179		Self::Borrowed(_) => false,
180		}
181		}
182		}
183
184		impl<T: Clone> $Name<'_, T> {
185
186		/// Return the contained data in it's owned form.
187		///
188		/// If it's borrowed this will clone it.
189		pub fn into_owned(self) -> T {
190		match self {
191		Self::Owned(v) => v,
192		Self::Borrowed(v) => v.clone(),
193		}
194		}
195
196		/// Internally converts the type into it's owned variant.
197		///
198		/// Conversion from a reference to the owned variant is done by cloning.
199		///
200		/// *This returns a `&mut T` and as such can be used to "unconditionally"
201		/// get an `&mut T`*. Be aware that while this works with both `MaybeOwned`
202		/// and `MaybeOwnedMut` it also converts it to an owned variant in both
203		/// cases. So while it's the best way to get a `&mut T` for `MaybeOwned`
204		/// for `MaybeOwnedMut` it's preferable to use `as_mut` from `AsMut`.
205		///
206		/// ## Example
207		///
208		/// ```
209		/// use maybe_owned::MaybeOwned;
210		///
211		/// #[derive(Clone, Debug, PartialEq, Eq)]
212		/// struct PseudoBigData(u8);
213		///
214		/// let data = PseudoBigData(12);
215		///
216		/// let mut maybe: MaybeOwned<PseudoBigData> = (&data).into();
217		/// assert_eq!(false, maybe.is_owned());
218		///
219		/// {
220		/// let reference = maybe.make_owned();
221		/// assert_eq!(&mut PseudoBigData(12), reference);
222		/// }
223		/// assert!(maybe.is_owned());
224		/// ```
225		pub fn make_owned(&mut self) -> &mut T {
226		match self {
227		Self::Owned(v) => v,
228		Self::Borrowed(v) => {
229		*self = Self::Owned(v.clone());
230		match self {
231		Self::Owned(v) => v,
232		Self::Borrowed(..) => unreachable!(),
233		}
234		}
235		}
236		}
237		}
238
239		impl<T> Deref for $Name<'_, T> {
240		type Target = T;
241
242	881k	fn deref(&self) -> &T {
243	881k	match self {
244	285k	Self::Owned(v) => v,
245	595k	Self::Borrowed(v) => v,
246		}
247	881k	}
248		}
249
250		impl<T> AsRef<T> for $Name<'_, T> {
251	881k	fn as_ref(&self) -> &T {
252	881k	self
253	881k	}
254		}
255
256		impl<T> From<T> for $Name<'_, T> {
257		fn from(v: T) -> Self {
258		Self::Owned(v)
259		}
260		}
261
262		impl<T> Borrow<T> for $Name<'_, T> {
263		fn borrow(&self) -> &T {
264		self
265		}
266		}
267
268		impl<T: Default> Default for $Name<'_, T> {
269		fn default() -> Self {
270		Self::Owned(T::default())
271		}
272		}
273
274		impl<'b, A: PartialEq<B>, B> PartialEq<$Name<'b, B>> for $Name<'_, A> {
275		#[inline]
276		fn eq(&self, other: &$Name<'b, B>) -> bool {
277		PartialEq::eq(self.deref(), other.deref())
278		}
279		}
280
281		impl<'a, T: Eq> Eq for $Name<'a, T> {}
282
283		impl<T: FromStr> FromStr for $Name<'_, T> {
284		type Err = T::Err;
285
286		fn from_str(s: &str) -> Result<Self, Self::Err> {
287		Ok(Self::Owned(T::from_str(s)?))
288		}
289		}
290
291		// TODO: Specify RHS
292		impl<T: PartialOrd> PartialOrd for $Name<'_, T> {
293		#[inline]
294		fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
295		PartialOrd::partial_cmp(self.deref(), other.deref())
296		}
297		}
298
299		impl<T: Ord> Ord for $Name<'_, T> {
300		#[inline]
301		fn cmp(&self, other: &Self) -> Ordering {
302		Ord::cmp(self.deref(), other.deref())
303		}
304		}
305
306		impl<T: Hash> Hash for $Name<'_, T> {
307		#[inline]
308		fn hash<H: Hasher>(&self, state: &mut H) {
309		Hash::hash(self.deref(), state)
310		}
311		}
312
313		impl<'a, T: fmt::Display> fmt::Display for $Name<'a, T> {
314		fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
315		match self {
316		Self::Owned(o) => fmt::Display::fmt(o, f),
317		Self::Borrowed(b) => fmt::Display::fmt(b, f),
318		}
319		}
320		}
321		};
322		}
323
324		common_impls!(MaybeOwned);
325		common_impls!(MaybeOwnedMut);
326
327		impl<'a, T> From<&'a T> for MaybeOwned<'a, T> {
328		fn from(v: &'a T) -> Self {
329		Self::Borrowed(v)
330		}
331		}
332
333		impl<'a, T> From<&'a mut T> for MaybeOwnedMut<'a, T> {
334		fn from(v: &'a mut T) -> Self {
335		Self::Borrowed(v)
336		}
337		}
338
339		impl<'a, T: ToOwned<Owned = T>> From<Cow<'a, T>> for MaybeOwned<'a, T> {
340		fn from(cow: Cow<'a, T>) -> MaybeOwned<'a, T> {
341		match cow {
342		Cow::Owned(v) => MaybeOwned::Owned(v),
343		Cow::Borrowed(v) => MaybeOwned::Borrowed(v),
344		}
345		}
346		}
347
348		impl<'a, T: ToOwned<Owned = T>> Into<Cow<'a, T>> for MaybeOwned<'a, T> {
349		fn into(self) -> Cow<'a, T> {
350		match self {
351		MaybeOwned::Owned(v) => Cow::Owned(v),
352		MaybeOwned::Borrowed(v) => Cow::Borrowed(v),
353		}
354		}
355		}
356
357		impl<T: Clone> Clone for MaybeOwned<'_, T> {
358		fn clone(&self) -> Self {
359		match self {
360		Self::Owned(v) => Self::Owned(v.clone()),
361		Self::Borrowed(v) => Self::Borrowed(v),
362		}
363		}
364		}
365
366		impl<T> MaybeOwned<'_, T> {
367		/// Returns a `&mut` if possible.
368		///
369		/// If the internal representation is borrowed (`&T`) then
370		/// this method will return `None`
371		pub fn as_mut(&mut self) -> Option<&mut T> {
372		match self {
373		MaybeOwned::Owned(value) => Some(value),
374		MaybeOwned::Borrowed(_) => None
375		}
376		}
377		}
378
379		impl<T: Clone> MaybeOwned<'_, T> {
380		/// Acquires a mutable reference to owned data.
381		///
382		/// Clones data if it is not already owned.
383		///
384		/// ## Example
385		///
386		/// ```
387		/// use maybe_owned::MaybeOwned;
388		///
389		/// #[derive(Clone, Debug, PartialEq, Eq)]
390		/// struct PseudoBigData(u8);
391		///
392		/// let data = PseudoBigData(12);
393		///
394		/// let mut maybe: MaybeOwned<PseudoBigData> = (&data).into();
395		/// assert_eq!(false, maybe.is_owned());
396		///
397		/// {
398		/// let reference = maybe.to_mut();
399		/// assert_eq!(&mut PseudoBigData(12), reference);
400		/// }
401		/// assert!(maybe.is_owned());
402		/// ```
403		///
404		#[deprecated = "use `make_owned` instead"]
405		pub fn to_mut(&mut self) -> &mut T {
406		match *self {
407		Self::Owned(ref mut v) => v,
408		Self::Borrowed(v) => {
409		*self = Self::Owned(v.clone());
410		match *self {
411		Self::Owned(ref mut v) => v,
412		Self::Borrowed(..) => unreachable!(),
413		}
414		}
415		}
416		}
417		}
418
419		impl<T> DerefMut for MaybeOwnedMut<'_, T> {
420		fn deref_mut(&mut self) -> &mut T {
421		match self {
422		Self::Owned(v) => v,
423		Self::Borrowed(v) => v,
424		}
425		}
426		}
427
428		impl<T> AsMut<T> for MaybeOwnedMut<'_, T> {
429		fn as_mut(&mut self) -> &mut T {
430		match self {
431		Self::Owned(v) => v,
432		Self::Borrowed(v) => v,
433		}
434		}
435		}
436
437		impl<T> BorrowMut<T> for MaybeOwnedMut<'_, T> {
438		fn borrow_mut(&mut self) -> &mut T {
439		self
440		}
441		}
442
443		#[cfg(test)]
444		mod tests {
445		use super::*;
446
447		type TestType = Vec<()>;
448
449		fn with_into<'a, I: Into<MaybeOwned<'a, TestType>>>(v: I) -> MaybeOwned<'a, TestType> {
450		v.into()
451		}
452
453		#[test]
454		fn is_owned() {
455		let data = TestType::default();
456		assert!(MaybeOwned::Owned(data).is_owned());
457		}
458
459		#[test]
460		fn make_owned() {
461		let mut a = MaybeOwned::Borrowed(&12u8);
462		assert!(!a.is_owned());
463		a.make_owned();
464		assert!(a.is_owned());
465		assert_eq!(&*a, &12);
466		}
467
468		#[test]
469		fn into_with_owned() {
470		//ty check if it accepts references
471		let data = TestType::default();
472		assert!(with_into(data).is_owned())
473		}
474		#[test]
475		fn into_with_borrow() {
476		//ty check if it accepts references
477		let data = TestType::default();
478		assert!(!with_into(&data).is_owned());
479		}
480
481		#[test]
482		fn clone_owned() {
483		let maybe = MaybeOwned::<TestType>::default();
484		assert!(maybe.clone().is_owned());
485		}
486
487		#[test]
488		fn clone_borrow() {
489		let data = TestType::default();
490		let maybe: MaybeOwned<TestType> = (&data).into();
491		assert!(!maybe.clone().is_owned());
492		}
493
494		#[test]
495		fn to_mut() {
496		let data = TestType::default();
497		let mut maybe: MaybeOwned<TestType> = (&data).into();
498		assert!(!maybe.is_owned());
499		{
500		#[allow(deprecated)]
501		let _mut_ref = maybe.to_mut();
502		}
503		assert!(maybe.is_owned());
504		}
505
506		#[test]
507		fn into_inner() {
508		let data = vec![1u32, 2];
509		let maybe: MaybeOwned<Vec<u32>> = (&data).into();
510		assert_eq!(data, maybe.into_owned());
511		}
512
513		#[test]
514		fn has_default() {
515		#[derive(Default)]
516		struct TestType(u8);
517		let _x: MaybeOwned<TestType> = Default::default();
518		}
519
520		#[test]
521		fn has_clone() {
522		#[derive(Clone)]
523		struct TestType(u8);
524		let _x = TestType(12).clone();
525		}
526
527		#[test]
528		fn has_deref() {
529		let a = MaybeOwned::Owned(vec![1u8]);
530		let _ = a.len();
531
532		let a = MaybeOwnedMut::Owned(vec![1u8]);
533		let _ = a.len();
534		}
535
536		#[test]
537		fn has_deref_mut() {
538		let mut a = MaybeOwnedMut::Owned(vec![1u8]);
539		a[0] = 12u8;
540		}
541
542		#[test]
543		fn has_partial_eq() {
544		#[derive(PartialEq)]
545		struct TestType(f32);
546
547		let n = TestType(33.0);
548		let a = MaybeOwned::Owned(TestType(42.0));
549		let b = MaybeOwned::Borrowed(&n);
550		let c = MaybeOwned::Owned(TestType(33.0));
551
552		assert_eq!(a == b, false);
553		assert_eq!(b == c, true);
554		assert_eq!(c == a, false);
555		}
556
557		#[test]
558		fn has_eq() {
559		#[derive(PartialEq, Eq)]
560		struct TestType(i32);
561
562		let n = TestType(33);
563		let a = MaybeOwned::Owned(TestType(42));
564		let b = MaybeOwned::Borrowed(&n);
565		let c = MaybeOwned::Owned(TestType(33));
566
567		assert_eq!(a == b, false);
568		assert_eq!(b == c, true);
569		assert_eq!(c == a, false);
570		}
571
572		#[test]
573		fn has_partial_ord() {
574		#[derive(PartialEq, PartialOrd)]
575		struct TestType(f32);
576
577		let n = TestType(33.0);
578		let a = MaybeOwned::Owned(TestType(42.0));
579		let b = MaybeOwned::Borrowed(&n);
580		let c = MaybeOwned::Owned(TestType(33.0));
581
582		assert_eq!(a > b, true);
583		assert_eq!(b > c, false);
584		assert_eq!(a < c, false);
585		}
586
587		#[test]
588		fn has_ord() {
589		#[derive(PartialEq, Eq, PartialOrd, Ord)]
590		struct TestType(i32);
591
592		let n = TestType(33);
593		let a = MaybeOwned::Owned(TestType(42));
594		let b = MaybeOwned::Borrowed(&n);
595		let c = MaybeOwned::Owned(TestType(33));
596
597		assert_eq!(a > b, true);
598		assert_eq!(b > c, false);
599		assert_eq!(a < c, false);
600		}
601
602		#[test]
603		fn has_hash() {
604		use std::collections::HashMap;
605
606		let mut map = HashMap::new();
607		map.insert(MaybeOwned::Owned(42), 33);
608
609		assert_eq!(map.get(&MaybeOwned::Borrowed(&42)), Some(&33));
610		}
611
612		#[test]
613		fn has_borrow() {
614		let v = MaybeOwned::Owned(42);
615		let _ = Borrow::<u8>::borrow(&v);
616
617		let v = MaybeOwnedMut::Owned(42);
618		let _ = Borrow::<u8>::borrow(&v);
619		}
620
621		#[test]
622		fn has_borrow_mut() {
623		let mut v = MaybeOwnedMut::Owned(42);
624		let _ = BorrowMut::<u8>::borrow_mut(&mut v);
625		}
626
627		#[test]
628		fn has_as_ref() {
629		let v = MaybeOwned::Owned(42);
630		let _ = AsRef::<u8>::borrow(&v);
631
632		let v = MaybeOwnedMut::Owned(42);
633		let _ = AsRef::<u8>::borrow(&v);
634		}
635
636		#[test]
637		fn has_as_mut() {
638		// uses a as_mut method
639		let mut v: MaybeOwned<u8> = (&11).into();
640		assert_eq!(v.as_mut(), None);
641
642		let mut v: MaybeOwned<u8> = 12.into();
643		assert_eq!(v.as_mut(), Some(&mut 12));
644
645		// uses AsMut
646		let mut v = MaybeOwnedMut::Owned(42);
647		let _ = AsMut::<u8>::borrow_mut(&mut v);
648		}
649
650		#[test]
651		fn has_display() {
652		let n = 33;
653		let a = MaybeOwned::Owned(42);
654		let b = MaybeOwned::Borrowed(&n);
655
656		let s = format!("{} {}", a, b);
657
658		assert_eq!(s, "42 33");
659		}
660
661		#[test]
662		fn from_cow() {
663		use std::borrow::Cow;
664
665		fn test<'a, V: Into<MaybeOwned<'a, i32>>>(v: V, n: i32) {
666		assert_eq!(*v.into(), n)
667		}
668
669		let n = 33;
670		test(Cow::Owned(42), 42);
671		test(Cow::Borrowed(&n), n);
672		}
673
674		#[test]
675		fn into_cow() {
676		use std::borrow::Cow;
677
678		fn test<'a, V: Into<Cow<'a, i32>>>(v: V, n: i32) {
679		assert_eq!(*v.into(), n)
680		}
681
682		let n = 33;
683		test(MaybeOwned::Owned(42), 42);
684		test(MaybeOwned::Borrowed(&n), n);
685		}
686
687		#[test]
688		fn from_str() {
689		let as_string = "12";
690		//assumption as_string is convertable to u32
691		assert_eq!(12u32, as_string.parse().unwrap());
692		assert_eq!(MaybeOwned::Owned(12u32), as_string.parse().unwrap());
693		}
694
695		#[test]
696		fn as_ref() {
697		let data = TestType::default();
698		let maybe_owned = MaybeOwned::Borrowed(&data);
699		let _ref: &TestType = maybe_owned.as_ref();
700		assert_eq!(&data as const _ as usize, _ref as const _ as usize);
701		}
702
703		#[test]
704		fn borrow() {
705		use std::borrow::Borrow;
706
707		let data = TestType::default();
708		let maybe_owned = MaybeOwned::Borrowed(&data);
709		let _ref: &TestType = maybe_owned.borrow();
710		assert_eq!(&data as const _ as usize, _ref as const _ as usize);
711		}
712
713		#[test]
714		fn reborrow_mut() {
715		let value = vec![0u32];
716		let mut value = MaybeOwnedMut::Owned(value);
717		let mut reborrow = MaybeOwnedMut::Borrowed(value.deref_mut());
718		reborrow.push(1);
719		assert_eq!(&[0, 1], &value[..]);
720		}
721		}