pub struct GenVec<T, G = usize, I = usize, GenIndex = (I, G)> { /* private fields */ }
Expand description
Vec
indexed with generational indexes.
GenVec
manages its own generational indexes and allocates and deallocates
indexes appropriately. Indexes constructed or allocated by external sources
should not be used.
If a single Vec
with generational indexes is required, then using GenVec
is useful. If generational indexes must be allocated and deallocated
externally or if multiple vectors are required, then the Allocator
and
UnmanagedGenVec
may be more useful.
Generational indexes are allocated on GenVec::insert()
and are deallocated
with GenVec::remove()
.
§Type Parameters
§T
T
is the element value type like the T
in Vec<T>
.
§G
G
is the generation type. G
is usually a type like u16 or u32.
By default, G is a usize.
Generation types must implement:
The range of values for G
determines how many generations a single index
can be used. Assume a u8 is used and a single index is allocated and
deallocated 255 times. After the 255th allocation, the index will never be
allocated again. For GenVec
, an index which will
never be re-used is essentially equivalent to wasted memory which will not
be reclaimed.
Note that for a u8, the maximum value (255) serves as a tombstone marker indicating that the index can no longer be used (otherwise a generational index with generation 255 could always access the value).
Assuming a single index is allocated and deallocated every second, a u16 would take (2^16 - 1) seconds to exhaust an index which is roughly 18 hours. A u32 would take (2^32 - 1) seconds which is more than 136 years.
§I
I
is the index type. I
is usually a type like usize. By default, I
is a usize.
Index types must implement:
Incrementable
Into<usize>
The range of values for I
determines the maximum limit on how many
concurrent entities may exist. If a u8 is used, a maximum of 256
values exist at any point in time.
§GenIndex
GenIndex
is the type which the generational index should be returned as. A tuple
like (I, G)
can be used or a custom type. By default, (I, G)
is used.
The generational index type is generally treated like an opaque identifier. While a tuple is useful, a custom type may be desired so a generational index is only used with collections which take the custom type.
GenIndex
types must implement:
From<(I, G)> for GenIndex
Into<(I, G)> for GenIndex
Implementations§
Source§impl<T, G, I, GenIndex> GenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> GenVec<T, G, I, GenIndex>
Sourcepub fn with_capacity(capacity: usize) -> Selfwhere
I: Default,
pub fn with_capacity(capacity: usize) -> Selfwhere
I: Default,
Constructs an inner Vec
with the given capacity.
See Vec::with_capacity
for additional information.
Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if the innner Vec
is empty.
See Vec::is_empty
for additional information.
Sourcepub fn capacity(&self) -> usize
pub fn capacity(&self) -> usize
Returns the capacity of the inner Vec
.
See Vec::capacity
for additional information.
Sourcepub fn reserve(&mut self, additional: usize)
pub fn reserve(&mut self, additional: usize)
Reserves additional capacity of the inner Vec
.
See Vec::reserve
for additional information.
Sourcepub fn reserve_exact(&mut self, additional: usize)
pub fn reserve_exact(&mut self, additional: usize)
Reserves additional capacity of the inner Vec
.
See Vec::reserve_exact
for additional information.
Source§impl<T, G, I, GenIndex> GenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> GenVec<T, G, I, GenIndex>
Sourcepub fn insert(&mut self, value: T) -> Result<GenIndex, Error>where
GenIndex: From<(I, G)> + Into<(I, G)>,
G: Clone + Default + PartialOrd,
I: Clone + Incrementable,
pub fn insert(&mut self, value: T) -> Result<GenIndex, Error>where
GenIndex: From<(I, G)> + Into<(I, G)>,
G: Clone + Default + PartialOrd,
I: Clone + Incrementable,
Inserts a new value into the collection.
The index of the value may be at any position in the underlying Vec
.
If there are no available positions, then the new value may be pushed
onto the end of the Vec
.
On success, the generational index of the element is returned.
§Errors
Errors are returned if:
- a generational index cannot be created
§Panics
Panics if the index or generation has exceeded the maximum value possible.
Sourcepub fn contains_index(&self, gen_index: GenIndex) -> bool
pub fn contains_index(&self, gen_index: GenIndex) -> bool
Returns true if an element exists for the generational index.
Sourcepub fn get(&self, gen_index: GenIndex) -> Result<&T, Error>
pub fn get(&self, gen_index: GenIndex) -> Result<&T, Error>
Returns a reference to the element at the given index if the generation matches.
See slice::get
for additional information.
§Errors
Errors are returned if:
- the index is out of bounds
- the generation of the generational index is not equal to the generation associated with the element
Sourcepub fn get_mut(&mut self, gen_index: GenIndex) -> Result<&mut T, Error>
pub fn get_mut(&mut self, gen_index: GenIndex) -> Result<&mut T, Error>
Returns a mutable reference to the element at the given index if the generation matches.
See slice::get_mut
for additional information.
§Errors
Errors are returned if:
- the index is out of bounds
- the generation of the generational index is not equal to the generation associated with the element
Sourcepub unsafe fn get_unchecked(&self, index: usize) -> &T
pub unsafe fn get_unchecked(&self, index: usize) -> &T
Returns a reference to the element at the given index.
See slice::get_unchecked
for additional information.
§Safety
There is no bounds check and no generation check performed. If the index is out of bounds, undefined behavior will occur.
Sourcepub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T
pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T
Returns a mutable reference to the element at the given index.
See slice::get_unchecked_mut
for additional information.
§Safety
There is no bounds check and no generation check performed. If the index is out of bounds, undefined behavior will occur.
Sourcepub fn set(&mut self, gen_index: GenIndex, value: T) -> Result<(G, T), Error>
pub fn set(&mut self, gen_index: GenIndex, value: T) -> Result<(G, T), Error>
Sets a value at the given index if the generation is equal to the generation associated with the existing element.
Returns the previous generation and the value for the element if successful.
§Errors
Errors are returned if:
- the index is out of bounds
- the generation of the generational index is less than the generation associated with the element
§Panics
- if the generation is greater than the current generation associated with the element.
Sourcepub fn remove(&mut self, gen_index: GenIndex) -> Result<(), Error>
pub fn remove(&mut self, gen_index: GenIndex) -> Result<(), Error>
Removes access to an element which matches the generation of the element.
§Errors
Errors are returned if:
- the index is out of bounds
- the generation is less than or equal to the existing generation
§Panics
- if the generation is greater than the current generation associated with the element.
- if the generation could not be incremented