Enum maybe_owned::MaybeOwned

pub enum MaybeOwned<'a, T: 'a> {
    Owned(T),
    Borrowed(&'a T),
}

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::Onwed 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 (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

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)));

#[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 });

Variants

Owned(T)

owns T

Borrowed(&'a T)

has a reference to T

Methods

impl<'a, T> MaybeOwned<'a, T>

fn is_owned(&self) -> bool

returns true if the data is owned else false

impl<'a, T> MaybeOwned<'a, T> where
    T: Clone, 

fn to_mut(&mut self) -> &mut T

Aquires 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());

fn into_owned(self) -> T

Extracts the owned data.

If the data is borrowed it is cloned before being extracted.

Trait Implementations

impl<'a, T: Debug + 'a> Debug for MaybeOwned<'a, T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, T> Deref for MaybeOwned<'a, T>

type Target = T

The resulting type after dereferencing

fn deref(&self) -> &T

The method called to dereference a value

impl<'a, T> From<&'a T> for MaybeOwned<'a, T>

fn from(v: &'a T) -> MaybeOwned<'a, T>

Performs the conversion.

impl<'a, T> From<T> for MaybeOwned<'a, T>

fn from(v: T) -> MaybeOwned<'a, T>

Performs the conversion.

impl<'a, T> Default for MaybeOwned<'a, T> where
    T: Default, 

fn default() -> Self

Returns the "default value" for a type.

impl<'a, T> Clone for MaybeOwned<'a, T> where
    T: Clone, 

fn clone(&self) -> MaybeOwned<'a, T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.