Crate stable_id

This crate mainly deals with issuing and maintaining stability of indices. It provides 4 structs and each helps in different area.

This library was created for my game development endeavor. Not going great on that front as I kept restarting the project. However, I saw these utility structures coming back multiple times so I’m making a crate for them.

In version 0.2.0, you can supply custom Id tuple structs that are based on unsigned integers (from 8bit to 64bits). The id type needs to be derived with the following:

// Minimal needed for all traits that are introduced by this crate.
#[derive(derive_stable_id::StableId)]
struct Id(u8);


// These are needed under normal circumstances.
#[derive(derive_stable_id::StableId)]
struct Id32(u32);

let x: stable_id::Eids<Id32> = Default::default();
let x: stable_id::Sequence<Id32> = Default::default();
let x: stable_id::SparseEntities<Id32, String> = Default::default();
let x: stable_id::Entities<Id32, String> = Default::default();
let x: stable_id::Tec<Id32, String> = Default::default();

Use cases

Struct	Type	Suggestion	Description
Eids	Id	Dense data	You want a way to create ids, and do care about recovering ids.
Sequence	Id	Sparse data	You want a way to create ids, and don’t care about recovering ids, but you don’t want to use the HashMap-based Entities struct.
Entities	Collection	Dense data	The go-to collection of this library.
SparseEntities	Collection	Sparse data	You want mix sequence (ids not recycled) and HashMap together.
Tec	Collection	Dense data	You want to use a vec to store data, but need constant entity removal. Tec reclaims the spaces for you as you insert more new items.

Structs

• Eids
  Stands for Entity Id generator (ids are redeemable). Basically a counter with a B-tree based free “set” (list).
• Entities
  This is a lazily memory-compact version of SparseEntities. Use cases are the same but there are different tradeoffs.
• Sequence
  An abstracted monotonically increasing counter structure. Once you claim an id you can’t go back.
• SparseEntities
  This is a sandwich of HashMap and Sequence.
• Tec
  Short for tombstone-based vector. Inspired by generational-arena, but without the generation stuff.

Traits

• CastUsize
  Trait for casting between an unsigned integer to a usize, and vice versa. Note: to() would panic if the value is greater or equal to the type’s max.
• Inner
  Trait for projecting the inner value of the Id’s tuple, i.e. returning u32 for Id(u32).
• Maximum
  A trait that describes the max value of an unsigned integer. This trait is used to detect overflow. Also, it’s used like a NULL terminator for the free list in [Tec].
• Predecessor
  Predecessor trait for numbers.
• Successor
  Successor trait for numbers.

Derive Macros

• StableId
  Derives all traits introduced by the stable-id-traits crate. The struct should be a tuple which contains an unsigned numeric primitive type.