Struct Loaned 

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

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

Thus, for the duration of 't, one cannot mutably access this value. However, unlike LoanedMut, one can immutably access it.

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

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

Dropping

The value held by a Loaned 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 Loaned panics.

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

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

Implementations

impl<'t, T> Loaned<'t, T>

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

where T: Loanable<'t>,

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

pub fn new(value: T) -> Self

Creates a Loaned without actually loaning it. If you want to loan it, use Loaned::loan or Loaned::borrow.

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.

pub fn borrow(&self) -> &'t T::Target

where T: Loanable<'t>,

Borrows the pointee of the value, returning a reference valid for 't.

impl<'t, T> Loaned<'t, T>

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

Merges multiple LoanedMut values.

Example

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

impl<'t, T> Loaned<'t, T>

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

Creates a Loaned with multiple sub-loans.

Example

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

Trait Implementations

impl<'t, T: Clone> Clone for Loaned<'t, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'t, T: Debug> Debug for Loaned<'t, T>

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<'t, T> Deref for Loaned<'t, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'t, T: Display> Display for Loaned<'t, T>

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

Available on crate feature alloc only.

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

Converts to this type from the input type.

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

fn from(value: Loaned<'t, MaybeUninit<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<MaybeUninit<Loaned<'t, T>>> for Loaned<'t, MaybeUninit<T>>

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

Converts to this type from the input type.

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

fn from(value: T) -> Self

Converts to this type from the input type.

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

Available on crate feature alloc only.

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

Converts to this type from the input type.

impl<'t, T: Hash> Hash for Loaned<'t, T>

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'t, T: Ord> Ord for Loaned<'t, T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'t, 'u, T: PartialEq<U>, U> PartialEq<Loaned<'u, U>> for Loaned<'t, T>

fn eq(&self, other: &Loaned<'u, U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'t, 'u, T: PartialOrd<U>, U> PartialOrd<Loaned<'u, U>> for Loaned<'t, T>

fn partial_cmp(&self, other: &Loaned<'u, U>) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

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

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

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

impl<'t, T: Eq> Eq for Loaned<'t, T>

impl<'t, T: Sync> Send for Loaned<'t, T>

Like &T, Loaned<T> is only Send if T is Sync.

Otherwise, code could cause data races:

use loaned::Loaned;
use std::cell::Cell;
let x = Loaned::new(Box::new(Cell::new(123)));
let y = x.borrow();
let x = std::thread::scope(|s| {
  let h = s.spawn(move || {
    x.set(456); // <- unsynchronized write
    x
  });
  y.get(); // // <- unsynchronized read
  h.join().unwrap()
});
loaned::drop!(x);

If you need to safely send this value, you can convert it to a LoanedMut<'t, T> with Into.