gen_value::vec

Struct GenVec

Source
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:

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>

Source

pub fn new() -> Self
where I: Default,

Constructs a new inner Vec.

See Vec::new for additional information.

Source

pub fn with_capacity(capacity: usize) -> Self
where I: Default,

Constructs an inner Vec with the given capacity.

See Vec::with_capacity for additional information.

Source

pub fn len(&self) -> usize

Returns the length of the inner Vec.

See Vec::len for additional information.

Source

pub fn is_empty(&self) -> bool

Returns true if the innner Vec is empty.

See Vec::is_empty for additional information.

Source

pub fn capacity(&self) -> usize

Returns the capacity of the inner Vec.

See Vec::capacity for additional information.

Source

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

Reserves additional capacity of the inner Vec.

See Vec::reserve for additional information.

Source

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>
where I: Into<usize>,

Source

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.

Source

pub fn contains_index(&self, gen_index: GenIndex) -> bool
where GenIndex: Into<(I, G)>, G: PartialEq,

Returns true if an element exists for the generational index.

Source

pub fn get(&self, gen_index: GenIndex) -> Result<&T, Error>
where GenIndex: Into<(I, G)>, G: PartialEq,

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
Source

pub fn get_mut(&mut self, gen_index: GenIndex) -> Result<&mut T, Error>
where GenIndex: Into<(I, G)>, G: PartialEq,

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
Source

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.

Source

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.

Source

pub fn set(&mut self, gen_index: GenIndex, value: T) -> Result<(G, T), Error>
where GenIndex: Into<(I, G)>, G: PartialOrd,

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.
Source

pub fn remove(&mut self, gen_index: GenIndex) -> Result<(), Error>
where GenIndex: From<(I, G)> + Into<(I, G)>, G: Clone + PartialOrd + Incrementable, I: Clone,

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

Trait Implementations§

Source§

impl<T: Debug, G: Debug, I: Debug, GenIndex: Debug> Debug for GenVec<T, G, I, GenIndex>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<T, G, I, GenIndex> Default for GenVec<T, G, I, GenIndex>
where I: Default,

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<T, G, I, GenIndex> Index<GenIndex> for GenVec<T, G, I, GenIndex>
where GenIndex: Into<(I, G)>, I: Into<usize>, G: PartialEq,

Source§

type Output = T

The returned type after indexing.
Source§

fn index(&self, gen_index: GenIndex) -> &Self::Output

Performs the indexing (container[index]) operation. Read more
Source§

impl<T, G, I, GenIndex> IndexMut<GenIndex> for GenVec<T, G, I, GenIndex>
where I: Into<usize>, GenIndex: Into<(I, G)>, G: PartialEq,

Source§

fn index_mut(&mut self, gen_index: GenIndex) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation. Read more

Auto Trait Implementations§

§

impl<T, G, I, GenIndex> Freeze for GenVec<T, G, I, GenIndex>
where I: Freeze, GenIndex: Freeze,

§

impl<T, G, I, GenIndex> RefUnwindSafe for GenVec<T, G, I, GenIndex>

§

impl<T, G, I, GenIndex> Send for GenVec<T, G, I, GenIndex>
where I: Send, GenIndex: Send, G: Send, T: Send,

§

impl<T, G, I, GenIndex> Sync for GenVec<T, G, I, GenIndex>
where I: Sync, GenIndex: Sync, G: Sync, T: Sync,

§

impl<T, G, I, GenIndex> Unpin for GenVec<T, G, I, GenIndex>
where I: Unpin, GenIndex: Unpin, G: Unpin, T: Unpin,

§

impl<T, G, I, GenIndex> UnwindSafe for GenVec<T, G, I, GenIndex>
where I: UnwindSafe, GenIndex: UnwindSafe, G: UnwindSafe, T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.