Struct LoanedMut

pub struct LoanedMut<'t, T> { /* private fields */ }

LoanedMut<'t, T> connotes ownership of a value T, with the caveat that allocations owned by it are mutably loaned for 't (i.e. something else may hold an &'t mut reference to such allocations).

Thus, for the duration of 't, one cannot access this value.

One can, however, store this value somewhere with LoanedMut::place, which will ensure that it cannot be used for the duration of 't.

Taking the value out of a LoanedMut can be done with the take! macro, which will statically ensure that 't has expired.

Dropping

The value held by a LoanedMut can only be dropped once 't expires. Since there is no way in the type system to enforce this, nor any way to check this at runtime, dropping a LoanedMut panics.

If leaking is intentional, use a ManuallyDrop<LoanedMut<'t, T>>.

To drop the inner value, use the drop! macro, which will statically ensure that 't has expired.

Implementations

impl<'t, T> LoanedMut<'t, T>

pub fn loan(value: T) -> (&'t mut T::Target, Self)

where T: Loanable<'t> + DerefMut,

Constructs a LoanedMut from a given smart pointer, returning the mutable borrow along with the loaned pointer.

Examples found in repository

examples/safe_arena.rs (line 33)

  fn new_chunk(capacity: usize) -> (&'t mut [Option<T>], LoanedMut<'t, Box<[Option<T>]>>) {
    let mut chunk = Vec::with_capacity(capacity);
    chunk.resize_with(capacity, || None);
    let chunk = chunk.into_boxed_slice();
    let (cursor, chunk) = LoanedMut::loan(chunk);
    (cursor, chunk)
  }

pub fn new(value: T) -> Self

Creates a LoanedMut without actually loaning it. If you want to loan it, use LoanedMut::loan.

pub fn place(self, place: &'t mut impl Place<'t, T>)

Stores the contained value into a given place. See the Place trait for more.

Examples found in repository

examples/tree_building.rs (line 55)

fn main() {
  // First, we create a single node `a`, which has two holes, `b` and `c`.
  // ```text
  //    a
  //   / \
  // ?b   ?c
  // ```
  // `a` is a `LoanedMut<Tree>`, whilst `b` and `c` are `&mut Tree`s.
  let (a, b, c) = new_node();

  // Next, we fill one of those holes, `b`, with a leaf:
  // ```text
  //    a
  //   / \
  //  1   ?c
  // ```
  *b = Tree::Leaf(1);

  // Now, we create another node, `x`, with holes `y` and `z`:
  // ```text
  //   a        x
  //  / \      / \
  // 1   ?c  ?y   ?z
  // ```
  let (x, y, z) = new_node();

  // We fill `y` with another leaf:
  // ```text
  //   a        x
  //  / \      / \
  // 1   ?c   2   ?z
  // ```
  *y = Tree::Leaf(2);

  // Now, we fill the hole `c` with the node `x`.
  // ```text
  //   a
  //  / \
  // 1  / \
  //   2   ?z
  // ```
  // We still have a mutable reference to the hole `z`, even though we just
  // moved ownership of `x` – this is the key power of `Loaned` values.
  x.place(c); // this is like `*c = x`, except it accepts `Loaned` values.

  // Finally, we can fill the hole `z` (which is a mutable reference to data now owned by `a`):
  // ```text
  //   a
  //  / \
  // 1  / \
  //   2   3
  // ```
  *z = Tree::Leaf(3);

  // All of the borrows have expired, so we can now take the tree out of `a`:
  let a = take!(a);

  println!("{a:?}");
  assert_eq!(format!("{a:?}"), "Node(Leaf(1), Node(Leaf(2), Leaf(3)))");

  // If we tried to use one of the borrows now, we would get an error from the borrow checker.
  // *z = Tree::Leaf(0xBAD);
}

impl<'t, T> LoanedMut<'t, T>

pub fn merge( value: T, f: impl for<'i> FnOnce(&'i mut T, &'i MergeMut<'t, 'i>), ) -> Self

Merges multiple LoanedMut values.

Example

use loaned::LoanedMut;
let a = LoanedMut::new(1);
let b = LoanedMut::new(2);
let ab: LoanedMut<(u32, u32)> = LoanedMut::merge(Default::default(), |ab, m| {
  m.place(a, &mut ab.0);
  m.place(b, &mut ab.1);
});

impl<'t, T> LoanedMut<'t, T>

pub fn loan_with<L>( value: T, f: impl for<'i> FnOnce(&'i mut T, &'i LoanWithMut<'t, 'i>) -> L, ) -> (L, Self)

Creates a LoanedMut with multiple sub-loans.

Example

use loaned::LoanedMut;
let ((a, b), ab) = LoanedMut::loan_with((Box::new(0), Box::new(0)), |ab, l| {
  (l.loan_mut(&mut ab.0), l.loan_mut(&mut ab.1))
});
*a = 1;
*b = 2;
assert_eq!(loaned::take!(ab), (Box::new(1), Box::new(2)));

Examples found in repository

examples/tree_building.rs (lines 77-85)

fn new_node<'t>() -> (LoanedMut<'t, Tree>, &'t mut Tree, &'t mut Tree) {
  let ((left, right), root) = LoanedMut::loan_with(
    Tree::Node(Default::default(), Default::default()),
    |tree, l| {
      let Tree::Node(left, right) = tree else {
        unreachable!()
      };
      (l.loan_mut(left), l.loan_mut(right))
    },
  );
  (root, left, right)
}

Trait Implementations

impl<'t, T> Debug for LoanedMut<'t, T>

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

Formats the value using the given formatter.

impl<'t, T: Default> Default for LoanedMut<'t, T>

fn default() -> Self

Returns the “default value” for a type.

impl<'t, T> Drop for LoanedMut<'t, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'t, T, const N: usize> From<[LoanedMut<'t, T>; N]> for LoanedMut<'t, [T; N]>

fn from(value: [LoanedMut<'t, T>; N]) -> Self

Converts to this type from the input type.

impl<'t, A> From<(LoanedMut<'t, A>,)> for LoanedMut<'t, (A,)>

fn from(value: (LoanedMut<'t, A>,)) -> Self

Converts to this type from the input type.

impl<'t, A, B> From<(LoanedMut<'t, A>, LoanedMut<'t, B>)> for LoanedMut<'t, (A, B)>

fn from(value: (LoanedMut<'t, A>, LoanedMut<'t, B>)) -> Self

Converts to this type from the input type.

impl<'t, A, B, C> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>)> for LoanedMut<'t, (A, B, C)>

fn from(value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>)) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>)> for LoanedMut<'t, (A, B, C, D)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>)> for LoanedMut<'t, (A, B, C, D, E)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E, F> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>)> for LoanedMut<'t, (A, B, C, D, E, F)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E, F, G> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>)> for LoanedMut<'t, (A, B, C, D, E, F, G)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E, F, G, H> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>)> for LoanedMut<'t, (A, B, C, D, E, F, G, H)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E, F, G, H, I> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>, LoanedMut<'t, I>)> for LoanedMut<'t, (A, B, C, D, E, F, G, H, I)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>, LoanedMut<'t, I>), ) -> Self

Converts to this type from the input type.

impl<'t, A, B, C, D, E, F, G, H, I, J> From<(LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>, LoanedMut<'t, I>, LoanedMut<'t, J>)> for LoanedMut<'t, (A, B, C, D, E, F, G, H, I, J)>

fn from( value: (LoanedMut<'t, A>, LoanedMut<'t, B>, LoanedMut<'t, C>, LoanedMut<'t, D>, LoanedMut<'t, E>, LoanedMut<'t, F>, LoanedMut<'t, G>, LoanedMut<'t, H>, LoanedMut<'t, I>, LoanedMut<'t, J>), ) -> Self

Converts to this type from the input type.

impl<'t, T> From<Box<LoanedMut<'t, T>>> for LoanedMut<'t, Box<T>>

fn from(value: Box<LoanedMut<'t, T>>) -> Self

Converts to this type from the input type.

impl<'t, T> From<Loaned<'t, T>> for LoanedMut<'t, T>

fn from(value: Loaned<'t, T>) -> Self

Converts to this type from the input type.

impl<'t, T> From<LoanedMut<'t, MaybeUninit<T>>> for MaybeUninit<LoanedMut<'t, T>>

fn from(value: LoanedMut<'t, MaybeUninit<T>>) -> Self

Converts to this type from the input type.

impl<'t, T> From<MaybeUninit<LoanedMut<'t, T>>> for LoanedMut<'t, MaybeUninit<T>>

fn from(value: MaybeUninit<LoanedMut<'t, T>>) -> Self

Converts to this type from the input type.

impl<'t, T> From<T> for LoanedMut<'t, T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<'t, T> From<Vec<LoanedMut<'t, T>>> for LoanedMut<'t, Vec<T>>

fn from(value: Vec<LoanedMut<'t, T>>) -> Self

Converts to this type from the input type.

impl<'t, T> Placeable<'t, T> for LoanedMut<'t, T>

fn place(self, place: &'t mut impl Place<'t, T>)