Struct rental::RentRef

pub struct RentRef<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> where T: FixedDeref { /* fields omitted */ }

A struct representing a particular (owner, rental) pair.

All such structs share a common API, but it is merely a convention enforced by the rental macro. The capabilities of a rental struct cannot be fully described as a trait without language support for HKT (Higher-Kinded Types). What methods can be expressed in a trait are documented in the Rental and RentalMut traits.

A rental struct can implement Deref, but only if the rented type is Deref and its target does not contain the 'rental lifetime in its signature.

Methods

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> RentRef<'rental, T, B> where T: FixedDeref

fn new<F__>(owner: T, f: F__) -> RentRef<'rental, T, B> where F__: for<'a__> FnOnce(&'a__ T::Target) -> &'a__ B

Instantiate a new shared rental pair. owner is the object from which a value will be rented. The closure takes a reborrowed shared reference to the owner's Deref target, and returns the rented value. Within this closure, the special 'rental lifetime is "existential" and cannot be unified with any external lifetime. This is crucial in that it prevents any borrow of the owner from escaping from the closure other than as a return value.

fn try_new<E__, F__>(owner: T,
                     f: F__)
                     -> Result<RentRef<'rental, T, B>, (E__, T)> where F__: for<'a__> FnOnce(&'a__ T::Target) -> Result<&'a__ B, E__>

As new, but the closure returns a Result with a generic error. In the event of such failure, this method will return Err with a tuple of the error itself and the owner object.

fn owner(&self) -> &T

Borrows the owner.

fn rent<'s__, F__, R__>(&'s__ self, f: F__) -> R__ where F__: for<'a__> FnOnce(&'s__ &'a__ B) -> R__, R__: 's__

Executes a closure on the existentially borrowed rental. The closure may return anything, including a borrow, as long as the existential 'rental lifetime does not appear in the type signature.

Trait Implementations

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Rental for RentRef<'rental, T, B> where T: FixedDeref

type Owner = T

type Rental = &'rental B

unsafe fn rental(&self) -> &&'rental B

This returns to you the rented value outside of an existential closure. This is unsafe because the lifetime substituted for 'rental here is a lie and does not reflect the true lifetime of the value. Only use this if you have no alternative, and think very carefully about how you're using the value to prevent it from outliving the rental struct, or inserting into it data that will not live long enough.

fn from_parts(owner: T, rent: &'rental B) -> Self

This will produce a rental struct from component parts. Not unsafe because, if you already have the components safely, combining them in this way does not introduce any additional unsafety.

unsafe fn into_parts(self) -> (T, &'rental B)

This will decompose a rental struct into its component parts. This is obviously unsafe because one may drop the owner while retaining the borrow.

fn into_owner(self) -> T

This will consume a rental struct and return to you the owner, discarding the rented value.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Deref for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>::Rental: Deref<Target=B>

type Target = RentRef<'rental, T, B>::Rental::Target

The resulting type after dereferencing

fn deref(&self) -> &RentRef<'rental, T, B>::Rental::Target

The method called to dereference a value

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> AsRef<B> for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref<Target=B>

fn as_ref(&self) -> &B

Performs the conversion.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Borrow<B> for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref<Target=B>

fn borrow(&self) -> &B

Immutably borrows from an owned value.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> PartialEq for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref, RentRef<'rental, T, B>::Target: PartialEq

fn eq(&self, other: &RentRef<'rental, T, B>) -> bool

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

fn ne(&self, other: &RentRef<'rental, T, B>) -> bool

This method tests for !=.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Eq for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref, RentRef<'rental, T, B>::Target: Eq

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> PartialOrd for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref, RentRef<'rental, T, B>::Target: PartialOrd

fn partial_cmp(&self, other: &RentRef<'rental, T, B>) -> Option<Ordering>

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

fn lt(&self, other: &RentRef<'rental, T, B>) -> bool

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

fn le(&self, other: &RentRef<'rental, T, B>) -> bool

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

fn gt(&self, other: &RentRef<'rental, T, B>) -> bool

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

fn ge(&self, other: &RentRef<'rental, T, B>) -> bool

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

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Ord for RentRef<'rental, T, B> where T: FixedDeref, RentRef<'rental, T, B>: Deref, RentRef<'rental, T, B>::Target: Ord

fn cmp(&self, other: &RentRef<'rental, T, B>) -> Ordering

This method returns an Ordering between self and other.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Hash for RentRef<'rental, T, B> where T: FixedDeref, &'a__ B: Hash

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Debug for RentRef<'rental, T, B> where T: FixedDeref, &'a__ B: Debug

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

Formats the value using the given formatter.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Display for RentRef<'rental, T, B> where T: FixedDeref, &'a__ B: Display

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

Formats the value using the given formatter.

impl<'rental, T: FixedDeref + 'rental, B: ?Sized + 'rental> Drop for RentRef<'rental, T, B> where T: FixedDeref

fn drop(&mut self)

A method called when the value goes out of scope.