Struct rental::RentMut

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

A struct representing a particular mutable (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 and DerefMut, but only if the rented type is Deref/DerefMut and its target does not contain the 'rental lifetime in its signature.

Methods

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> RentMut<'rental, T, B> where 'static: 'rental

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

Instantiate a new mutable rental pair. owner is the object from which a value will be rented. The closure takes a reborrowed mutable 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<RentMut<'rental, T, B>, (E__, T)> where F__: for<'a__> FnOnce(&'a__ mut T::Target) -> Result<&'a__ mut 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 rent<'s__, F__, R__>(&'s__ self, f: F__) -> R__ where F__: for<'a__> FnOnce(&'s__ &'a__ mut 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.

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

As rent but the rental is mutable.

Trait Implementations

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

type Owner = T

type Rental = &'rental mut B

unsafe fn rental(&self) -> &&'rental mut 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 mut 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 mut 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 + DerefMut + 'rental, B: ?Sized + 'rental> RentalMut for RentMut<'rental, T, B> where 'static: 'rental

unsafe fn rental_mut(&mut self) -> &mut Self::Rental

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.

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> Deref for RentMut<'rental, T, B> where 'static: 'rental

type Target = B

The resulting type after dereferencing

fn deref(&self) -> &B

The method called to dereference a value

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> DerefMut for RentMut<'rental, T, B> where 'static: 'rental

fn deref_mut(&mut self) -> &mut RentMut<'rental, T, B>::Rental::Target

The method called to mutably dereference a value

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> AsRef<B> for RentMut<'rental, T, B> where 'static: 'rental

fn as_ref(&self) -> &B

Performs the conversion.

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> AsMut<B> for RentMut<'rental, T, B> where 'static: 'rental

fn as_mut(&mut self) -> &mut B

Performs the conversion.

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> Borrow<B> for RentMut<'rental, T, B> where 'static: 'rental

fn borrow(&self) -> &B

Immutably borrows from an owned value.

impl<'rental, T: FixedDeref + DerefMut + 'rental, B: ?Sized + 'rental> BorrowMut<B> for RentMut<'rental, T, B> where 'static: 'rental

fn borrow_mut(&mut self) -> &mut B

Mutably borrows from an owned value.

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

fn drop(&mut self)

A method called when the value goes out of scope.