rental 0.2.2

A macro to generate self-borrowing structs, plus premade types for convenience.

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 Symbols 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 associated type aliases for common rental scenarios. The documentation for the rental macro describes the kinds of items that can be generated.