Crate rental [−] [src]
A macro to generate self-borrowing structs, plus a few predefined type aliases for convenience.
Overview
It can sometimes occur in the course of designing an API that you find yourself in a situation where you need to store, in a single struct, both an owned value and a borrow of that value. Rust's concept of ownership and borrowing is quite flexible, but can't quite express such a scenario.
One example might be libloading
. That crate provides a Library
struct
that defines methods to borrow Symbol
s from it. These symbols are bounded
by the lifetime of the library, and are thus considered a borrow. Under
normal circumstances, one would be unable to store both the library and the
symbols within a single struct, but the macro defined in this crate allows
you to define a struct that is capable of storing both simultaneously.
This crate uses the term "rental" to describe this concept of a borrow that co-exsists with its owner in the same struct. The borrow itself is called the "rented" type. The "owner", naturally, is the item in the struct that owns the borrow.
The API consists of the rental
macro, which generates
rental structs, and a few premade instantiations of this macro handling
rented bare references. If you only need to rent references, see
RentRef
and RentMut
, as
well as the related type aliases for common rental scenarios. The
documentation for the rental
macro describes the
kinds of items that can be generated.
Macros
rental |
This macro is the bedrock of the API. It allows you to define three different kinds of items related to renting. |
Structs
MapMut |
A mapper that can convert one rental into another, provided they have identical owner types. |
MapRef |
A mapper that can convert one rental into another, provided they have identical owner types. |
RentMut |
A struct representing a particular mutable (owner, rental) pair. |
RentRef |
A struct representing a particular (owner, rental) pair. |
Traits
FixedDeref |
This trait indicates both that the type can be dereferenced, and that when it is, the target has a fixed memory address while it is held by a rental struct. |
Rental |
This trait is implemented for all rental structs. |
RentalMut |
This trait is implemented for all mutable rental structs. |
Type Definitions
RentArc |
A predefined type that rents references from an |
RentBox |
A predefined type that rents references from a |
RentBoxMut |
A predefined type that rents mutable references from a |
RentMutex |
A predefined type that rents references from a |
RentMutexMut |
A predefined type that rents mutable references from a |
RentRefCell |
A predefined type that rents references from a |
RentRefCellMut |
A predefined type that rents mutable references from a |
RentRwLock |
A predefined type that rents references from an |
RentRwLockMut |
A predefined type that rents mutable references from an |
RentString |
A predefined type that rents references from a |
RentStringMut |
A predefined type that rents mutable references from a |
RentVec |
A predefined type that rents references from a |
RentVecMut |
A predefined type that rents mutable references from a |