Struct mucell::Ref [−] [src]

pub struct Ref<'b, T: 'b> { /* fields omitted */ }

An immutable reference to a MuCell. Normally you should dereference to get at the object, but after transformation with Ref::map or Ref::filter_map you might instead use .into_inner().

Methods

impl<'b, T: Clone> Ref<'b, T>
[src]

Copies a Ref.

The MuCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::clone(...). A Clone implementation or a method would interfere with the widespread use of r.borrow().clone() to clone the contents of a MuCell.

impl<'b, T: 'static> Ref<'b, T>
[src]

Consumes the Ref, returning the wrapped value.

The 'static constraint on T is what makes this possible; there is no longer any need to keep the borrow alive, and so the Ref itself can be consumed while keeping the contained value.

Examples

use mucell::{MuCell, Ref};
use std::borrow::Cow;

let c = MuCell::new("foo");

let r1: Ref<Cow<str>> = Ref::map(c.borrow(), |s| Cow::from(*s));
let r2: Ref<String> = Ref::map(r1, |s| s.into_owned());
let string: String = r2.into_inner();

impl<'b, T: ?Sized> Ref<'b, Cow<'b, T>> where
    T: ToOwned,
    T::Owned: 'static, 
[src]

Extracts the owned data.

Copies the data if it is not already owned.

This code is precisely equivalent to Ref::map(self, |cow| cow.into_owned()).into_inner() and is purely a convenience method because Ref<Cow<T>> is a common case.

Examples

use mucell::{MuCell, Ref};
use std::borrow::Cow;

let c = MuCell::new("foo");

let r: Ref<Cow<str>> = Ref::map(c.borrow(), |s| Cow::from(*s));
let string: String = r.into_owned();

impl<'b, T> Ref<'b, T>
[src]

Make a new Ref for a component of the borrowed data.

The MuCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::map(...). A method would interfere with methods of the same name on the contents of a MuCell used through Deref.

Memory unsafety

This function is marked as unsafe because it is possible (though not the easiest thing) to subvert memory safety by storing a reference to the wrapped value. This is a deficiency which cannot be solved without Rust supporting HKT. It’d need something like where F: (for<'f> FnOnce(T) -> U where T: 'f, U: 'f).

The only class of transformation functions that can structurally be known to be safe in current Rust is those with no non-static environment; the map function embodies that constraint and should be used where possible instead of this function.

Example

use mucell::{MuCell, Ref};

let c = MuCell::new((5, 'b'));
let b1: Ref<&(u32, char)> = c.borrow();
let b2: Ref<&u32> = Ref::map(b1, |t| &t.0);
assert_eq!(*b2, 5)

This is a safe version of map_unsafe, imposing the constraint that F is 'static.

This is the only way to make it safe in a pre-HKT world: by preventing the closure from capturing any non-static environment. Anything beyond that will require caution to ensure safety.

Make a new Ref for a optional component of the borrowed data, e.g. an enum variant.

The MuCell is already immutably borrowed, so this cannot fail.

This is an associated function that needs to be used as Ref::filter_map(...). A method would interfere with methods of the same name on the contents of a MuCell used through Deref.

Memory unsafety

This function is marked as unsafe because it is possible (though not the easiest thing) to subvert memory safety by storing a reference to the wrapped value. This is a deficiency which cannot be solved without Rust supporting HKT. It’d need something like where F: (for<'f> FnOnce(T) -> Option<U> where T: 'f, U: 'f).

The only class of transformation functions that can structurally be known to be safe in current Rust is those with no non-static environment; the map function embodies that constraint and should be used where possible instead of this function.

Example

use mucell::{MuCell, Ref};

let c = MuCell::new(Ok(5));
let b1: Ref<&Result<u32, ()>> = c.borrow();
let b2: Ref<&u32> = Ref::filter_map(b1, |o| o.as_ref().ok()).unwrap();
assert_eq!(*b2, 5)

This is a safe version of filter_map_unsafe, imposing the constraint that F is 'static.

This is the only way to make it safe in a pre-HKT world: by preventing the closure from capturing any non-static environment. Anything beyond that will require caution to ensure safety.

Trait Implementations

impl<'b, T: Deref + 'b> Deref for Ref<'b, T>
[src]

The resulting type after dereferencing

The method called to dereference a value

impl<'b, T: DerefMut + 'b> DerefMut for Ref<'b, T>
[src]

The method called to mutably dereference a value