Enum laxcow::LaxCow

pub enum LaxCow<'a, B: ?Sized, O = B> {
    Borrowed(&'a B),
    Owned(O),
}

Clone-on-write smart pointer with relaxed trait constraints relative to Cow.

LaxCow does not constrain owned type in its type definition, but in methods that specifically require this. Thus, Owned type is generic and may need to be explicitly defined when instantiating. Also, LaxCow isn’t strictly clone-on-write as not all instances of it support writing i.e. mutable access.

Examples

Simple usage

use laxcow::LaxCow;

let lc = LaxCow::Borrowed("foobar");

let lc2 = lc.clone();
assert_eq!(lc2, LaxCow::<_, String>::Borrowed("foobar"));

let owned = lc.into_owned();
assert_eq!(owned, "foobar".to_owned());

Usage not possible with Cow

Storing a borrowed struct which doesn’t implement Clone. This is possible because LaxCow::Owned variant is not restricted by the LaxCow::Borrowed variant via ToOwned trait.

use laxcow::LaxCow;

struct Foo;

let laxcow = LaxCow::<_, ()>::Borrowed(&Foo);

Cow definition by wrapping LaxCow

use laxcow::LaxCow;

struct Cow<'a, T: ?Sized + ToOwned>(LaxCow::<'a, T, T::Owned>);

Variants

Borrowed(&'a B)

Owned(O)

Implementations

impl<'a, B: ?Sized, O> LaxCow<'a, B, O>

pub const fn is_borrowed(&self) -> bool

Returns true if LaxCow contains borrowed item, false otherwise.

Examples

use laxcow::LaxCow;

// We don't care what owned type is as it is not used.
let borrowed = LaxCow::<i32, ()>::Borrowed(&42);

assert!(borrowed.is_borrowed());

pub const fn is_owned(&self) -> bool

Returns true if LaxCow contains owned item, false otherwise.

Examples

use laxcow::LaxCow;

// We don't care what borrowed type is as it is not used.
let owned = LaxCow::<(), i32>::Owned(42);

assert!(owned.is_owned());

pub fn to_mut(&mut self) -> &mut Owhere B: ToOwned<Owned = O>,

Returns mutable reference to the owned item.

If the item is currently borrowed, it will converted into owned via ToOwned trait before returning mutable reference to it.

Examples

use laxcow::LaxCow;

let mut borrowed = LaxCow::Borrowed(&42);
let mut owned = LaxCow::<i32, _>::Owned(42);

*borrowed.to_mut() += 10;
*owned.to_mut() += 10;

assert_eq!(borrowed, LaxCow::Owned(52));
assert_eq!(owned, LaxCow::Owned(52));

pub fn try_as_owned_mut(&mut self) -> Result<&mut O, &mut &'a B>

Attempts to get a mutable reference to the owned variant of the instance.

No conversion is attempted but mutable reference to the borrowed item is returned as an error.

Examples

use laxcow::LaxCow;

let mut borrowed = LaxCow::<_, String>::Borrowed("borrow");
let mut owned = LaxCow::<str, _>::Owned("own".to_owned());

assert_eq!(borrowed.try_as_owned_mut(), Err(&mut "borrow"));
assert_eq!(owned.try_as_owned_mut(), Ok(&mut "own".to_owned()));

As the borrowed item is not mutable referenced, it cannot be modified. However, the reference itself can be modified:

use laxcow::LaxCow;

let another = "another borrow";
let mut borrowed = LaxCow::<_, String>::Borrowed("borrow");

*borrowed.try_as_owned_mut().unwrap_err() = another;

assert_eq!(borrowed, LaxCow::<_, String>::Borrowed("another borrow"));

pub fn into_owned(self) -> Owhere B: ToOwned<Owned = O>,

Consumes LaxCow and returns owned item as is, or borrowed item via ToOwned trait conversion.

Examples

use laxcow::LaxCow;

let borrowed: LaxCow<_, String> = LaxCow::Borrowed("foobar");
let owned: LaxCow<str, _> = LaxCow::Owned("foobar".to_owned());

assert_eq!(borrowed.into_owned(), "foobar".to_owned());
assert_eq!(owned.into_owned(), "foobar".to_owned());

pub fn try_into_owned(self) -> Result<O, &'a B>

Attempts to transform the instance into its owned variant.

No conversion is attempted but the borrowed item is returned as an error.

Examples

use laxcow::LaxCow;

let mut borrowed = LaxCow::<_, String>::Borrowed("borrow");
let mut owned = LaxCow::<str, _>::Owned("own".to_owned());

assert_eq!(borrowed.try_into_owned(), Err("borrow"));
assert_eq!(owned.try_into_owned(), Ok("own".to_owned()));

Trait Implementations

impl<B: ?Sized, O> AsRef<B> for LaxCow<'_, B, O>where O: AsRef<B>,

fn as_ref(&self) -> &B

Converts this type into a shared reference of the (usually inferred) input type.

impl<B: ?Sized, O> Clone for LaxCow<'_, B, O>where O: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<B, O> Debug for LaxCow<'_, B, O>where B: Debug + ?Sized, O: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B: ?Sized, O> Default for LaxCow<'_, B, O>where O: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<B: ?Sized, O> Deref for LaxCow<'_, B, O>where O: Borrow<B>,

type Target = B

The resulting type after dereferencing.

fn deref(&self) -> &B

Dereferences the value.

impl<B, O> Display for LaxCow<'_, B, O>where B: Display + ?Sized, O: Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, B, O> From<Cow<'a, B>> for LaxCow<'a, B, O>where B: ToOwned<Owned = O> + ?Sized,

fn from(cow: Cow<'a, B>) -> Self

Converts to this type from the input type.

impl<'a, B, O> From<LaxCow<'a, B, O>> for Cow<'a, B>where B: ToOwned<Owned = O> + ?Sized,

fn from(laxcow: LaxCow<'a, B, O>) -> Self

Converts to this type from the input type.

impl<B, O> Hash for LaxCow<'_, B, O>where O: Borrow<B>, B: Hash + ?Sized,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<B, O> Ord for LaxCow<'_, B, O>where O: Borrow<B>, B: Ord + ?Sized,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<'a, 'b, B, O, B2: ?Sized, O2> PartialEq<LaxCow<'a, B2, O2>> for LaxCow<'b, B, O>where B: PartialEq<B2> + ?Sized, O: Borrow<B>, O2: Borrow<B2>,

fn eq(&self, other: &LaxCow<'a, B2, O2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<B, O> PartialOrd<LaxCow<'_, B, O>> for LaxCow<'_, B, O>where B: PartialOrd + ?Sized, O: Borrow<B>,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<B, O> Eq for LaxCow<'_, B, O>where B: Eq + ?Sized, O: Borrow<B>,