Struct Pair

pub struct Pair<O: Owner + ?Sized> { /* private fields */ }

A self-referential pair containing both some Owner and its Dependent.

The owner must be provided to construct a Pair, and the dependent is immediately created (borrowing from the owner). Both are stored together in the pair, which heap-allocates the owner so that the pair itself may be moved freely without invalidating any references stored inside the dependent.

Conceptually, the pair itself has ownership over the owner O, the owner is immutably borrowed by the dependent for the lifetime of the pair, and the dependent is owned by the pair and valid for the pair’s lifetime.

Constructors

There are many different constructors for Pair, each serving a different use case. There are three relevant factors to consider when deciding which constructor to use:

1. Can make_dependent fail (return Err)?
2. Does make_dependent require additional context?
3. Is your owner already stored in a Box?

The simplest constructor, which you should use if you answered “no” to all of the above questions, is Pair::new. It takes an O: Owner, and gives you a Pair<O> - doesn’t get much easier than that!

If your make_dependent can fail (meaning Owner::Error is not Infallible), you should use one of the try_* constructors.

If your make_dependent requires additional context (meaning Owner::Context is not ()), you should use one of the *_with_context constructors.

If your owner is already stored in a Box, you should use one of the *_from_box constructors.

Every combination of these is supported, up to the most powerful (and least ergonomic) Pair::try_new_from_box_with_context. You should use the simplest constructor you can for your implementation of Owner.

Implementations

impl<O: Owner + ?Sized> Pair<O>

pub fn try_new_with_context( owner: O, context: O::Context<'_>, ) -> Result<Self, (O, O::Error)>

where O: Sized,

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

Errors

If <O as Owner>::make_dependent returns an error.

pub fn try_new_from_box_with_context( owner: Box<O>, context: O::Context<'_>, ) -> Result<Self, (Box<O>, O::Error)>

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

Errors

If <O as Owner>::make_dependent returns an error.

pub fn owner(&self) -> &O

Returns a reference to the owner.

pub fn with_dependent<'self_borrow, F, T>(&'self_borrow self, f: F) -> T

where F: for<'any> FnOnce(&'self_borrow Dependent<'_, O>) -> T,

Calls the given closure, providing shared access to the dependent, and returns the value computed by the closure.

The closure must be able to work with a Dependent with any arbitrary lifetime that lives at least as long as the borrow of self. This is important because the dependent may be invariant over its lifetime, and the correct lifetime (lasting from the construction of self until drop) is inexpressible. For dependent types covariant over their lifetime, the closure may simply return the reference to the dependent, which may then be used as if this function directly returned a reference.

pub fn with_dependent_mut<'self_borrow, F, T>(&'self_borrow mut self, f: F) -> T

where F: for<'any> FnOnce(&'self_borrow mut Dependent<'_, O>) -> T,

Calls the given closure, providing exclusive access to the dependent, and returns the value computed by the closure.

The closure must be able to work with a Dependent with any arbitrary lifetime that lives at least as long as the borrow of self. This is important because mutable references are invariant over their type T, and the exact T here (a Dependent with a very specific lifetime lasting from the construction of self until drop) is inexpressible.

pub fn with_both<'self_borrow, F, T>(&'self_borrow self, f: F) -> T

where F: for<'any> FnOnce(&'self_borrow O, &'self_borrow Dependent<'_, O>) -> T,

Calls the given closure, providing shared access to both the owner and the dependent, and returns the value computed by the closure.

The closure must be able to work with a Dependent with any arbitrary lifetime that lives at least as long as the borrow of self. See the documentation of with_dependent for more information on this.

pub fn with_both_mut<'self_borrow, F, T>(&'self_borrow mut self, f: F) -> T

where F: for<'any> FnOnce(&'self_borrow O, &'self_borrow mut Dependent<'_, O>) -> T,

Calls the given closure, providing shared access to the owner and exclusive access to the dependent, and returns the value computed by the closure.

The closure must be able to work with a Dependent with any arbitrary lifetime that lives at least as long as the borrow of self. See the documentation of with_dependent_mut for more information on this.

pub fn into_boxed_owner(self) -> Box<O>

Consumes the Pair, dropping the dependent and returning the owner.

If you don’t need the returned owner in a Box, consider the convenience method Pair::into_owner, which moves the owner out of the box for you.

pub fn into_owner(self) -> O

where O: Sized,

Consumes the Pair, dropping the dependent and returning the owner.

If you manually box the returned owner for your own purposes, consider Pair::into_boxed_owner to avoid redundant reallocation.

impl<O: for<'any> Owner<Context<'any> = (), Error = Infallible> + ?Sized> Pair<O>

pub fn new(owner: O) -> Self

where O: Sized,

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

pub fn new_from_box(owner: Box<O>) -> Self

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

impl<O: for<'any> Owner<Context<'any> = ()> + ?Sized> Pair<O>

pub fn try_new(owner: O) -> Result<Self, (O, O::Error)>

where O: Sized,

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

Errors

If <O as Owner>::make_dependent returns an error.

pub fn try_new_from_box(owner: Box<O>) -> Result<Self, (Box<O>, O::Error)>

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

Errors

If <O as Owner>::make_dependent returns an error.

impl<O: Owner<Error = Infallible> + ?Sized> Pair<O>

pub fn new_with_context(owner: O, context: O::Context<'_>) -> Self

where O: Sized,

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

pub fn new_from_box_with_context(owner: Box<O>, context: O::Context<'_>) -> Self

Constructs a new Pair with the given Owner. The dependent will be computed through Owner::make_dependent during this construction.

See the “Constructors” section in the documentation of Pair for information on the differences between constructors.

Trait Implementations

impl<O: Owner + Debug + ?Sized> Debug for Pair<O>

where for<'any> Dependent<'any, O>: Debug,

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

Formats the value using the given formatter.

impl<O: for<'any> Owner<Context<'any> = (), Error = Infallible> + Default> Default for Pair<O>

fn default() -> Self

Returns the “default value” for a type.

impl<O: Owner + ?Sized> Drop for Pair<O>

The Drop implementation for Pair will drop both the dependent and the owner, in that order.

fn drop(&mut self)

Executes the destructor for this type.

impl<O> Send for Pair<O>

where O: Send + Owner + ?Sized, for<'any> Dependent<'any, O>: Send,

impl<O> Sync for Pair<O>

where O: Sync + Owner + ?Sized, for<'any> Dependent<'any, O>: Sync,