Struct Region 

pub struct Region<T> { /* private fields */ }

A handle-addressed store of T.

A thin typed membrane over slotmap::SlotMap<slotmap::DefaultKey, T>: values live in slotmap’s dense, cache-friendly, always-compact backing store, and every operation delegates to slotmap while exposing only typed Handle<T> values (raw DefaultKeys never escape). All operations are O(1).

Invariants upheld

• I1 — resolution: a fresh handle resolves via get to the inserted value until it is removed.
• I2 — tombstone: after remove(h), get(h) is None forever and a second remove(h) is a no-op None.
• I3 — no ABA: a stale handle — one whose slot has since been reused — never resolves to a live value. slotmap’s DefaultKey carries a generation that is bumped on removal, so the old handle fails the version check and yields None.
• I4 — accounting: len equals the number of live entries and is_empty agrees.
• I5 — drop-once: every live value is dropped exactly once — on remove (returned to the caller) or on Region drop — never twice, never leaked. slotmap owns the storage and therefore the drops.

Generation saturation

Version saturation (a slot whose generation would have to wrap) is slotmap’s responsibility: DefaultKey retires such a slot rather than wrapping a generation into alias, so a handle can never alias a future value — the classic generational-arena ABA caveat stays closed at the astronomically rare cost of one slot per 2^32 reuses. There is no hand-rolled retirement code in this crate.

Implementations

impl<T> Region<T>

pub fn new() -> Region<T>

Creates an empty region that allocates nothing until first use.

pub fn with_capacity(capacity: usize) -> Region<T>

Creates an empty region with space pre-reserved for capacity entries.

pub fn len(&self) -> usize

Number of live values (I4).

pub fn is_empty(&self) -> bool

Whether the region holds no live values (I4).

pub fn capacity(&self) -> usize

Current value-storage capacity, in entries.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more insertions.

Does nothing if the backing store already has room. After a churn that removes entries, the freed slots live on the free list, so re-inserting reuses existing capacity and does not grow unboundedly (the backing stays bounded by the high-water mark of live entries). Delegates to slotmap’s reserve; may allocate more than asked to avoid frequent reallocations. Panics if the new allocation size overflows usize.

pub fn insert(&mut self, value: T) -> Handle<T>

Inserts value, returning a fresh handle that resolves to it (I1).

pub fn get(&self, handle: Handle<T>) -> Option<&T>

Borrows the value for handle, or None if the handle is stale or removed (I1, I2, I3).

pub fn get_mut(&mut self, handle: Handle<T>) -> Option<&mut T>

Mutably borrows the value for handle, or None if stale/removed.

pub fn contains(&self, handle: Handle<T>) -> bool

Whether handle currently resolves to a live value.

pub fn remove(&mut self, handle: Handle<T>) -> Option<T>

Removes and returns the value for handle, or None if it is already stale/removed. After this, handle resolves to None forever (I2).

pub fn iter(&self) -> impl Iterator<Item = &T>

Iterates the live values in dense (cache-friendly) order. The order is unspecified and changes as elements are removed.

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T>

Mutably iterates the live values in dense order.

pub fn clear(&mut self)

Removes every value, invalidating all outstanding handles, while retaining allocated capacity. The region is reusable afterwards.

Trait Implementations

impl<T> Default for Region<T>

fn default() -> Region<T>

Returns the “default value” for a type.