% containerof - Macros supporting intrusive data structures in Rust.
An intrusive structure is a general-purpose structure directly embedded within a containing structure, in order to add that general-purpose facility to the container. As an example, one might use an intrusive "link" structure to allow objects to be organized in a linked-list:
#
extern crate containerof;
containerof_intrusive!;
#
While this module does not provide a linked-list implementation (for separation-of-concerns reasons, I believe a linked-list implementation belongs in a separate crate), it does provide some necessary abstractions for using intrusive structures:
- The
containerof_field_offset!
macro, which identifies the location of a field in a containing structure. This isn't too useful in itself, but is necessary to support: - The
containerof_intrusive!
macro, which provides a newtype that describes the translation between the "intrusive" field and the "container" structure.
Usage
Here is an example implementation of Church-numerals using an intrusive linked-list:
extern crate containerof;
use *;
containerof_intrusive!;
#
Concepts
containerof
uses three main concepts for working with intrusive
structures:
- The intrusive structure itself (
Church.next
in the above example); - The containing structure (
Church
); - The translation type, for getting a container from a field,
or vice-versa (
ChurchLink
).
In addition, there are three auxiliary structures for managing ownership and borrowing of intrusive structures:
OwnBox
, which is a pointer type representing ownership of the container (even if all you have is a field reference).BorrowBox
, which is a pointer type representing a borrow of the container.BorrowBoxMut
, which is a pointer type representing a mutable borrow of the container.
Contributing
- Fork it ( https://github.com/aidancully/containerof/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request