Struct supercow::Supercow [−] [src]

pub struct Supercow<'a, OWNED, BORROWED: ?Sized = OWNED, SHARED = Box<DefaultFeatures<'static> + 'static>, STORAGE = BoxedStorage, PTR = *const BORROWED> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED> { /* fields omitted */ }

The actual generic reference type.

See the module documentation for most of the details.

Most of the generics requirements you don't need to pay too much attention to if you aren't making custom SHARED or STORAGE types, etc. In general:

OWNED may be constrained to be Clone and/or BORROWED as ToOwned if cloning an inner value is needed.
External traits are defined against BORROWED.
PTR : PtrRead<BORROWED> means the operation is not available on Phantomcow.

Methods

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>`
[src]

`fn owned(inner: OWNED) -> Self where OWNED: SafeBorrow<BORROWED>`

Creates a new Supercow which owns the given value.

This can create a Supercow with a 'static lifetime.

`fn borrowed<T: Borrow<BORROWED> + ?Sized>(inner: &'a T) -> Self`

Creates a new Supercow which borrows the given value.

`fn shared<T>(inner: T) -> Self where T: ConstDeref<Target=BORROWED>, SHARED: SharedFrom<T>`

Creates a new Supercow using the given shared reference.

The reference must be convertible to SHARED via SharedFrom.

`fn clone_non_owned(this: &Self) -> Option<Self> where SHARED: Clone`

If this is non-owned, clone this and return it.

Otherwise, return None.

Example

use supercow::Supercow;

struct SomeNonCloneThing;

let owned: Supercow<SomeNonCloneThing> = SomeNonCloneThing.into();
assert!(Supercow::clone_non_owned(&owned).is_none());

let the_thing = SomeNonCloneThing;
let borrowed: Supercow<SomeNonCloneThing> = (&the_thing).into();
let also_borrowed = Supercow::clone_non_owned(&borrowed).unwrap();Run

Logically clone this without needing to clone OWNED.

If this Supercow is in owned mode, the owned value is first moved into a new shared reference so that OWNED does not need to be cloned.

Example

use supercow::Supercow;

struct NonCloneType(u32);

let mut first: Supercow<NonCloneType> =
  Supercow::owned(NonCloneType(42));
let second = Supercow::share(&mut first);

assert_eq!(42, (*first).0);
assert_eq!(42, (*second).0);Run

`fn extract_ref(this: &Self) -> Option<&'a BORROWED> where PTR: PtrRead<BORROWED>`

If this is borrowed, return the underlying reference with the original lifetime. Otherwise, return None.

The returned reference has a lifetime independent of this.

This can be used to bridge between Supercow APIs and mundane reference APIs without needing to restrict the lifetime to the Supercow, but as a result is only available if the contained reference is actually independent.

Example

use std::sync::Arc;

use supercow::Supercow;

let forty_two: u32 = 42;

let borrowed: Supercow<u32> = (&forty_two).into();
assert_eq!(Some(&forty_two), Supercow::extract_ref(&borrowed));

let owned: Supercow<u32> = forty_two.into();
assert_eq!(None, Supercow::extract_ref(&owned));

let shared: Supercow<u32> = Arc::new(forty_two).into();
assert_eq!(None, Supercow::extract_ref(&shared));Run

`fn into_inner(this: Self) -> OWNED where OWNED: Borrow<BORROWED>, BORROWED: ToOwned<Owned=OWNED>, PTR: PtrRead<BORROWED>`

Takes ownership of the underling value if needed, then returns it, consuming self.

`fn to_mut<'b>(&'b mut self) -> Ref<'b, Self> where OWNED: SafeBorrow<BORROWED>, BORROWED: ToOwned<Owned=OWNED>, PTR: PtrRead<BORROWED>`

Returns a (indirect) mutable reference to an underlying owned value.

If this Supercow does not currently own the value, it takes ownership. A Ref is then returned which allows accessing the mutable owned value directly.

Leak Safety

If the returned Ref is released without its destructor being run, the behaviour of the Supercow is unspecified (but does not result in memory unsafety).

`fn unborrow(this: Self) -> Supercow<'static, OWNED, BORROWED, SHARED, STORAGE, PTR> where OWNED: SafeBorrow<BORROWED>, BORROWED: ToOwned<Owned=OWNED>, PTR: PtrRead<BORROWED>`

If this is borrowed, clone the inner value so that the new Supercow has a 'static lifetime.

If the inner value is owned or shared, this simply returns the input unchanged.

Example

use supercow::Supercow;

let s = {
  let forty_two = 42u32;
  let by_ref: Supercow<u32> = Supercow::borrowed(&forty_two);
  // We can't return `by_ref` because it holds a reference to
  // `forty_two`. However, we can change that lifetime parameter
  // to `'static` and then move that out of the block.
  let by_val: Supercow<'static, u32> = Supercow::unborrow(by_ref);
  by_val
};
assert_eq!(42, *s);Run

`fn take_ownership<NS>(this: Self) -> Supercow<'static, OWNED, BORROWED, NS, STORAGE, PTR> where OWNED: SafeBorrow<BORROWED>, BORROWED: ToOwned<Owned=OWNED>, STORAGE: OwnedStorage<OWNED, NS>, PTR: PtrRead<BORROWED>`

Takes ownership of the underlying value, so that this Supercow has a 'static lifetime.

This may also change the SHARED type parameter arbitrarily.

Example

use supercow::Supercow;

let s = {
  let forty_two = 42u32;
  let by_ref: Supercow<u32> = Supercow::borrowed(&forty_two);
  // We can't return `by_ref` because it holds a reference to
  // `forty_two`. However, we can change that lifetime parameter
  // to `'static` and then move that out of the block.
  let by_val: Supercow<'static, u32> =
    Supercow::take_ownership(by_ref);
  by_val
};
assert_eq!(42, *s);Run

`fn phantom(this: Self) -> Phantomcow<'a, OWNED, BORROWED, SHARED, STORAGE>`

Converts this Supercow into a Phantomcow.

Trait Implementations

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Drop for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>`
[src]

`fn drop(&mut self)`

A method called when the value goes out of scope. Read more

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Send for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, OWNED: Send, &'a BORROWED: Send, SHARED: Send, STORAGE: Send`
[src]

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Sync for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, OWNED: Sync, &'a BORROWED: Sync, SHARED: Sync, STORAGE: Sync`
[src]

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Deref for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, PTR: PtrRead<BORROWED>`
[src]

`type Target = BORROWED`

The resulting type after dereferencing

`fn deref(&self) -> &BORROWED`

The method called to dereference a value

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Borrow<BORROWED> for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, PTR: PtrRead<BORROWED>`
[src]

`fn borrow(&self) -> &BORROWED`

Immutably borrows from an owned value. Read more

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> AsRef<BORROWED> for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, PTR: PtrRead<BORROWED>`
[src]

`fn as_ref(&self) -> &BORROWED`

Performs the conversion.

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> Clone for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, OWNED: Clone + SafeBorrow<BORROWED>, SHARED: Clone`
[src]

`fn clone(&self) -> Self`

Returns a copy of the value. Read more

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

Performs copy-assignment from source. Read more

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> From<OWNED> for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, OWNED: SafeBorrow<BORROWED>`
[src]

`fn from(inner: OWNED) -> Self`

Performs the conversion.

`impl<'a, OWNED, BORROWED: ?Sized, SHARED, STORAGE, PTR> From<&'a OWNED> for Supercow<'a, OWNED, BORROWED, SHARED, STORAGE, PTR> where BORROWED: 'a, *const BORROWED: PointerFirstRef, STORAGE: OwnedStorage<OWNED, SHARED>, PTR: PtrWrite<BORROWED>, OWNED: Borrow<BORROWED>`
[src]

`fn from(inner: &'a OWNED) -> Self`

Performs the conversion.

`impl<'a, OWNED, SHARED, STORAGE> From<Rc<OWNED>> for Supercow<'a, OWNED, OWNED, SHARED, STORAGE> where SHARED: SharedFrom<Rc<OWNED>>, STORAGE: OwnedStorage<OWNED, SHARED>, OWNED: 'a, *const OWNED: PointerFirstRef`
[src]

`fn from(rc: Rc<OWNED>) -> Self`

Performs the conversion.

`impl<'a, OWNED, SHARED, STORAGE> From<Arc<OWNED>> for Supercow<'a, OWNED, OWNED, SHARED, STORAGE> where SHARED: SharedFrom<Arc<OWNED>>, STORAGE: OwnedStorage<OWNED, SHARED>, OWNED: 'a, *const OWNED: PointerFirstRef`
[src]