pub struct UnmanagedGenVec<T, G = usize, I = usize, GenIndex = (I, G)> { /* private fields */ }
Expand description
Vec
indexed with externally managed generational indexes.
UnmanagedGenVec
does not manage its own indexes. An external source must
allocate and deallocate indexes with generations appropriately.
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.
§Safety
The generation at an index in the inner Vec
should always be greater than or
equal to any generational index’s generation for the same index.
If the generation has a maximum value (e.g. u8::MAX
), then the maximum value
should serve as a tombstone to indicate that the index cannot be used.
Any generational index with the maximum generation should never
be used for any method except set_next_gen
.
§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 required in most functions. I
is turned into a
usize to index into the inner Vec
. By default, I
is a usize.
Index types must implement:
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. 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:
Into<(I, G)> for GenIndex
Implementations§
Source§impl<T, G, I, GenIndex> UnmanagedGenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> UnmanagedGenVec<T, G, I, GenIndex>
Sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
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> UnmanagedGenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> UnmanagedGenVec<T, G, I, GenIndex>
Sourcepub fn push_with_gen(&mut self, generation: G, value: T)
pub fn push_with_gen(&mut self, generation: G, value: T)
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 get_gen(&self, index: I) -> Option<&G>
pub fn get_gen(&self, index: I) -> Option<&G>
Returns the generation associated with the element at the index.
Returns None
if the index is out of bounds.
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. To increase the generation, a call to
set_next_gen
must be called first.
Sourcepub fn set_or_push(
&mut self,
gen_index: GenIndex,
value: T,
) -> Result<Option<(G, T)>, Error>
pub fn set_or_push( &mut self, gen_index: GenIndex, value: T, ) -> Result<Option<(G, T)>, Error>
Sets or pushes the element at the index if the generation is equal to the existing generation associated with the element.
Returns the previous generation and the value for the element if replacing an existing value.
This method is a convenience method for the newest allocated
generational index. Either the newest allocated generationl index is
for an existing index or it is for the immediate next index if a
value were to be pushed to the Vec
.
§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 index is greater than the length of the inner vector
- if the generation is greater than the current generation associated
with the element. To increase the generation, a call to
set_next_gen
must be called first.
Sourcepub fn set_next_gen(&mut self, gen_index: GenIndex) -> Result<G, Error>
pub fn set_next_gen(&mut self, gen_index: GenIndex) -> Result<G, Error>
Sets the next generation for an index. The gen_index
parameter is
composed of the index and the next generation of the current generation
associated with the element.
Returns the previous generation if successful.
§Errors
Errors are returned if:
- the index is out of bounds
- the generation is less than or equal to the existing generation associated with the element
§Panics
Panics if the generation is not the next generation after the existing generation associated with the element.
Sourcepub fn set_gen(&mut self, gen_index: GenIndex) -> Result<G, Error>
pub fn set_gen(&mut self, gen_index: GenIndex) -> Result<G, Error>
Sets the generation for an index.
Any existing generational indexes equal to or greater than the given generation could be considered valid again.
Normally, this method should never be called in a program. In exceptional conditions (such as when an index has exhausted all generations and all generational indexes referencing the index have been removed from the program), the method could be called.
§Errors
Errors are returned if:
- the index is out of bounds
Trait Implementations§
Source§impl<T: Clone, G: Clone, I: Clone, GenIndex: Clone> Clone for UnmanagedGenVec<T, G, I, GenIndex>
impl<T: Clone, G: Clone, I: Clone, GenIndex: Clone> Clone for UnmanagedGenVec<T, G, I, GenIndex>
Source§fn clone(&self) -> UnmanagedGenVec<T, G, I, GenIndex>
fn clone(&self) -> UnmanagedGenVec<T, G, I, GenIndex>
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreSource§impl<T: Debug, G: Debug, I: Debug, GenIndex: Debug> Debug for UnmanagedGenVec<T, G, I, GenIndex>
impl<T: Debug, G: Debug, I: Debug, GenIndex: Debug> Debug for UnmanagedGenVec<T, G, I, GenIndex>
Source§impl<T, G, I, GenIndex> Default for UnmanagedGenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> Default for UnmanagedGenVec<T, G, I, GenIndex>
Source§impl<T, G, I, GenIndex> Index<GenIndex> for UnmanagedGenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> Index<GenIndex> for UnmanagedGenVec<T, G, I, GenIndex>
Source§impl<T, G, I, GenIndex> IndexMut<GenIndex> for UnmanagedGenVec<T, G, I, GenIndex>
impl<T, G, I, GenIndex> IndexMut<GenIndex> for UnmanagedGenVec<T, G, I, GenIndex>
Source§impl<T: Ord, G: Ord, I: Ord, GenIndex: Ord> Ord for UnmanagedGenVec<T, G, I, GenIndex>
impl<T: Ord, G: Ord, I: Ord, GenIndex: Ord> Ord for UnmanagedGenVec<T, G, I, GenIndex>
Source§fn cmp(&self, other: &UnmanagedGenVec<T, G, I, GenIndex>) -> Ordering
fn cmp(&self, other: &UnmanagedGenVec<T, G, I, GenIndex>) -> Ordering
1.21.0 · Source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
Source§impl<T: PartialEq, G: PartialEq, I: PartialEq, GenIndex: PartialEq> PartialEq for UnmanagedGenVec<T, G, I, GenIndex>
impl<T: PartialEq, G: PartialEq, I: PartialEq, GenIndex: PartialEq> PartialEq for UnmanagedGenVec<T, G, I, GenIndex>
Source§fn eq(&self, other: &UnmanagedGenVec<T, G, I, GenIndex>) -> bool
fn eq(&self, other: &UnmanagedGenVec<T, G, I, GenIndex>) -> bool
self
and other
values to be equal, and is used by ==
.