gen_value::unmanaged

Struct UnmanagedGenVec

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

Source

pub fn new() -> Self

Constructs a new inner Vec.

See Vec::new for additional information.

Source

pub fn with_capacity(capacity: usize) -> Self

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> UnmanagedGenVec<T, G, I, GenIndex>

Source

pub fn push(&mut self, value: T)
where G: Default,

Pushes the default generation and value to the end of the inner Vec.

See Vec::push for additional information.

Source

pub fn push_with_gen(&mut self, generation: G, value: T)

Pushes a generation and value to the end of the inner Vec.

See Vec::push for additional information.

Source

pub fn contains_index(&self, gen_index: GenIndex) -> bool
where GenIndex: Into<(I, G)>, I: Into<usize>, 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)>, I: Into<usize>, 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)>, I: Into<usize>, 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 get_gen(&self, index: I) -> Option<&G>
where I: Into<usize>,

Returns the generation associated with the element at the index.

Returns None if the index is out of bounds.

Source

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

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

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

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

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

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.

Source

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

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>

Source§

fn clone(&self) -> UnmanagedGenVec<T, G, I, GenIndex>

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T: Debug, G: Debug, I: Debug, GenIndex: Debug> Debug for UnmanagedGenVec<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 UnmanagedGenVec<T, G, I, GenIndex>

Source§

fn default() -> Self

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

impl<T: Hash, G: Hash, I: Hash, GenIndex: Hash> Hash for UnmanagedGenVec<T, G, I, GenIndex>

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl<T, G, I, GenIndex> Index<GenIndex> for UnmanagedGenVec<T, G, I, GenIndex>
where I: Into<usize>, GenIndex: Into<(I, G)>, 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 UnmanagedGenVec<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
Source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · Source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more
Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<T: PartialOrd, G: PartialOrd, I: PartialOrd, GenIndex: PartialOrd> PartialOrd for UnmanagedGenVec<T, G, I, GenIndex>

Source§

fn partial_cmp( &self, other: &UnmanagedGenVec<T, G, I, GenIndex>, ) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · Source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Source§

impl<T: Eq, G: Eq, I: Eq, GenIndex: Eq> Eq for UnmanagedGenVec<T, G, I, GenIndex>

Source§

impl<T, G, I, GenIndex> StructuralPartialEq for UnmanagedGenVec<T, G, I, GenIndex>

Auto Trait Implementations§

§

impl<T, G, I, GenIndex> Freeze for UnmanagedGenVec<T, G, I, GenIndex>

§

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

§

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

§

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

§

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

§

impl<T, G, I, GenIndex> UnwindSafe for UnmanagedGenVec<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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. 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> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.