Enum Oco 

pub enum Oco<'a, T: ?Sized + ToOwned + 'a> {
    Borrowed(&'a T),
    Counted(Arc<T>),
    Owned(<T as ToOwned>::Owned),
}

“Owned Clones Once”: a smart pointer that can be either a reference, an owned value, or a reference-counted pointer. This is useful for storing immutable values, such as strings, in a way that is cheap to clone and pass around.

The cost of the Clone implementation depends on the branch. Cloning the Oco::Borrowed variant simply copies the references (O(1)). Cloning the Oco::Counted variant increments a reference count (O(1)). Cloning the Oco::Owned variant requires an O(n) clone of the data.

For an amortized O(1) clone, you can use Oco::clone_inplace(). Using this method, Oco::Borrowed and Oco::Counted are still O(1). Oco::Owned does a single O(n) clone, but converts the object to the Oco::Counted branch, which means future clones will be O(1).

In general, you’ll either want to call clone_inplace() once, before sharing the Oco with other parts of your application (so that all future clones are O(1)), or simply use this as if it is a Cow with an additional branch for reference-counted values.

Variants

Borrowed(&'a T)

A static reference to a value.

Counted(Arc<T>)

A reference counted pointer to a value.

Owned(<T as ToOwned>::Owned)

An owned value.

Implementations

impl<T: ?Sized + ToOwned> Oco<'_, T>

pub fn into_owned(self) -> <T as ToOwned>::Owned

Converts the value into an owned value.

pub const fn is_borrowed(&self) -> bool

Checks if the value is Oco::Borrowed.

Examples

assert!(Oco::<str>::Borrowed("Hello").is_borrowed());
assert!(!Oco::<str>::Counted(Arc::from("Hello")).is_borrowed());
assert!(!Oco::<str>::Owned("Hello".to_string()).is_borrowed());

pub const fn is_counted(&self) -> bool

Checks if the value is Oco::Counted.

Examples

assert!(Oco::<str>::Counted(Arc::from("Hello")).is_counted());
assert!(!Oco::<str>::Borrowed("Hello").is_counted());
assert!(!Oco::<str>::Owned("Hello".to_string()).is_counted());

pub const fn is_owned(&self) -> bool

Checks if the value is Oco::Owned.

Examples

assert!(Oco::<str>::Owned("Hello".to_string()).is_owned());
assert!(!Oco::<str>::Borrowed("Hello").is_owned());
assert!(!Oco::<str>::Counted(Arc::from("Hello")).is_owned());

impl Oco<'_, str>

pub fn as_str(&self) -> &str

Returns a &str slice of this Oco.

Examples

let oco = Oco::<str>::Borrowed("Hello");
let s: &str = oco.as_str();
assert_eq!(s, "Hello");

impl Oco<'_, CStr>

pub fn as_c_str(&self) -> &CStr

Returns a &CStr slice of this Oco.

Examples

use std::ffi::CStr;

let oco =
    Oco::<CStr>::Borrowed(CStr::from_bytes_with_nul(b"Hello\0").unwrap());
let s: &CStr = oco.as_c_str();
assert_eq!(s, CStr::from_bytes_with_nul(b"Hello\0").unwrap());

impl Oco<'_, OsStr>

pub fn as_os_str(&self) -> &OsStr

Returns a &OsStr slice of this Oco.

Examples

use std::ffi::OsStr;

let oco = Oco::<OsStr>::Borrowed(OsStr::new("Hello"));
let s: &OsStr = oco.as_os_str();
assert_eq!(s, OsStr::new("Hello"));

impl Oco<'_, Path>

pub fn as_path(&self) -> &Path

Returns a &Path slice of this Oco.

Examples

use std::path::Path;

let oco = Oco::<Path>::Borrowed(Path::new("Hello"));
let s: &Path = oco.as_path();
assert_eq!(s, Path::new("Hello"));

impl<T> Oco<'_, [T]>

where [T]: ToOwned,

pub fn as_slice(&self) -> &[T]

Returns a &[T] slice of this Oco.

Examples

let oco = Oco::<[u8]>::Borrowed(b"Hello");
let s: &[u8] = oco.as_slice();
assert_eq!(s, b"Hello");

impl<'a, T> Oco<'a, T>

where T: ?Sized + ToOwned + 'a, for<'b> Arc<T>: From<&'b T>,

pub fn upgrade_inplace(&mut self)

Upgrades the value in place, by converting into Oco::Counted if it was previously Oco::Owned.

Examples

let mut oco1 = Oco::<str>::Owned("Hello".to_string());
assert!(oco1.is_owned());
oco1.upgrade_inplace();
assert!(oco1.is_counted());

pub fn clone_inplace(&mut self) -> Self

Clones the value with inplace conversion into Oco::Counted if it was previously Oco::Owned.

Examples

let mut oco1 = Oco::<str>::Owned("Hello".to_string());
let oco2 = oco1.clone_inplace();
assert_eq!(oco1, oco2);
assert!(oco1.is_counted());
assert!(oco2.is_counted());

Trait Implementations

impl<'b> Add<&'b str> for Oco<'_, str>

type Output = Oco<'static, str>

The resulting type after applying the + operator.

fn add(self, rhs: &'b str) -> Self::Output

Performs the + operation.

impl<'b> Add<Cow<'b, str>> for Oco<'_, str>

type Output = Oco<'static, str>

The resulting type after applying the + operator.

fn add(self, rhs: Cow<'b, str>) -> Self::Output

Performs the + operation.

impl<'b> Add<Oco<'b, str>> for Oco<'_, str>

type Output = Oco<'static, str>

The resulting type after applying the + operator.

fn add(self, rhs: Oco<'b, str>) -> Self::Output

Performs the + operation.

impl AsRef<Path> for Oco<'_, OsStr>

fn as_ref(&self) -> &Path

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

impl AsRef<Path> for Oco<'_, str>

fn as_ref(&self) -> &Path

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

impl<T: ?Sized + ToOwned> AsRef<T> for Oco<'_, T>

fn as_ref(&self) -> &T

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

impl<T: ?Sized + ToOwned> Borrow<T> for Oco<'_, T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<'a, T> Clone for Oco<'a, T>

where T: ?Sized + ToOwned + 'a, for<'b> Arc<T>: From<&'b T>,

fn clone(&self) -> Self

Returns a new Oco with the same value as this one. If the value is Oco::Owned, this will convert it into Oco::Counted, so that the next clone will be O(1).

Examples

String :

let oco = Oco::<str>::Owned("Hello".to_string());
let oco2 = oco.clone();
assert_eq!(oco, oco2);
assert!(oco2.is_counted());

Vec :

let oco = Oco::<[u8]>::Owned(b"Hello".to_vec());
let oco2 = oco.clone();
assert_eq!(oco, oco2);
assert!(oco2.is_counted());

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

Performs copy-assignment from source.

impl<T> Debug for Oco<'_, T>

where T: ToOwned + ?Sized + Debug,

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

Formats the value using the given formatter.

impl<T> Default for Oco<'_, T>

where T: ToOwned + ?Sized, T::Owned: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized + ToOwned> Deref for Oco<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, T> Deserialize<'a> for Oco<'static, T>

where T: ?Sized + ToOwned + 'a, T::Owned: DeserializeOwned,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'a>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for Oco<'_, T>

where T: ToOwned + ?Sized + Display,

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

Formats the value using the given formatter.

impl<'a, T, const N: usize> From<&'a [T; N]> for Oco<'a, [T]>

where [T]: ToOwned,

fn from(v: &'a [T; N]) -> Self

Converts to this type from the input type.

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

where T: ToOwned + ?Sized,

fn from(v: &'a T) -> Self

Converts to this type from the input type.

impl<T> From<Arc<T>> for Oco<'_, T>

where T: ToOwned + ?Sized,

fn from(v: Arc<T>) -> Self

Converts to this type from the input type.

impl<T> From<Box<T>> for Oco<'_, T>

where T: ToOwned + ?Sized,

fn from(v: Box<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<Cow<'a, T>> for Oco<'a, T>

where T: ToOwned + ?Sized,

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

Converts to this type from the input type.

impl From<Oco<'_, str>> for String

fn from(v: Oco<'_, str>) -> Self

Converts to this type from the input type.

impl<'a, T> From<Oco<'a, T>> for Cow<'a, T>

where T: ToOwned + ?Sized,

fn from(value: Oco<'a, T>) -> Self

Converts to this type from the input type.

impl<'a> From<Oco<'a, str>> for Oco<'a, [u8]>

fn from(v: Oco<'a, str>) -> Self

Converts to this type from the input type.

impl From<String> for Oco<'_, str>

fn from(v: String) -> Self

Converts to this type from the input type.

impl<T> From<Vec<T>> for Oco<'_, [T]>

where [T]: ToOwned<Owned = Vec<T>>,

fn from(v: Vec<T>) -> Self

Converts to this type from the input type.

impl<'a> FromIterator<Oco<'a, str>> for String

fn from_iter<T: IntoIterator<Item = Oco<'a, str>>>(iter: T) -> Self

Creates a value from an iterator.

impl<T> Hash for Oco<'_, T>

where T: ToOwned + ?Sized + Hash,

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<T> Ord for Oco<'_, T>

where T: ToOwned + ?Sized + Ord,

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'a, 'b, T: PartialEq> PartialEq<&'b [T]> for Oco<'a, [T]>

where [T]: ToOwned,

fn eq(&self, other: &&'b [T]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b> PartialEq<&'b str> for Oco<'a, str>

fn eq(&self, other: &&'b str) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialEq> PartialEq<[T]> for Oco<'_, [T]>

where [T]: ToOwned,

fn eq(&self, other: &[T]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b, T: PartialEq> PartialEq<Cow<'b, [T]>> for Oco<'a, [T]>

where [T]: ToOwned,

fn eq(&self, other: &Cow<'b, [T]>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b> PartialEq<Cow<'b, str>> for Oco<'a, str>

fn eq(&self, other: &Cow<'b, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialEq> PartialEq<Oco<'_, [T]>> for [T]

where [T]: ToOwned,

fn eq(&self, other: &Oco<'_, [T]>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialEq> PartialEq<Oco<'_, [T]>> for Vec<T>

where [T]: ToOwned,

fn eq(&self, other: &Oco<'_, [T]>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialEq<Oco<'_, str>> for String

fn eq(&self, other: &Oco<'_, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialEq<Oco<'_, str>> for str

fn eq(&self, other: &Oco<'_, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b, T: PartialEq> PartialEq<Oco<'a, [T]>> for &'b [T]

where [T]: ToOwned,

fn eq(&self, other: &Oco<'a, [T]>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b, T: PartialEq> PartialEq<Oco<'a, [T]>> for Cow<'b, [T]>

where [T]: ToOwned,

fn eq(&self, other: &Oco<'a, [T]>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b> PartialEq<Oco<'a, str>> for &'b str

fn eq(&self, other: &Oco<'a, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, 'b> PartialEq<Oco<'a, str>> for Cow<'b, str>

fn eq(&self, other: &Oco<'a, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'b, A, B> PartialEq<Oco<'b, B>> for Oco<'_, A>

where A: PartialEq<B> + ToOwned + ?Sized, B: ToOwned + ?Sized,

fn eq(&self, other: &Oco<'b, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialEq<String> for Oco<'_, str>

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialEq> PartialEq<Vec<T>> for Oco<'_, [T]>

where [T]: ToOwned,

fn eq(&self, other: &Vec<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialEq<str> for Oco<'_, str>

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'b, A, B> PartialOrd<Oco<'b, B>> for Oco<'_, A>

where A: PartialOrd<B> + ToOwned + ?Sized, B: ToOwned + ?Sized,

fn partial_cmp(&self, other: &Oco<'b, B>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, T> Serialize for Oco<'a, T>

where T: ?Sized + ToOwned + 'a, for<'b> &'b T: Serialize,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: ?Sized + ToOwned + Eq> Eq for Oco<'_, T>