Struct orx_fixed_vec::FixedVec

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

A fixed vector, FixedVec, is a vector with a strict predetermined capacity (see SplitVec for dynamic capacity version).

It provides the following features:

• It provides operations with the same complexity and speed as the standard vector.
• It makes sure that the data stays pinned in place.
  • FixedVec<T> implements PinnedVec<T> for any T;
  • FixedVec<T> implements PinnedVecSimple<T> for T: NotSelfRefVecItem;
  • Memory location of an item added to the fixed vector will never change unless the vector is dropped or cleared.
  • This allows the fixed vec to be converted into an ImpVec to enable immutable-push operations which allows for convenient, efficient and safe implementations of self-referencing data structures.

Implementations

impl<T> FixedVec<T>

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the vector elements.

impl<T> FixedVec<T>

pub fn new(fixed_capacity: usize) -> Self

Creates a new vector with the given fixed capacity.

Note that the vector can never grow beyond this capacity.

Examples

use orx_fixed_vec::prelude::*;

let mut vec = FixedVec::new(7);
vec.push(42);

assert_eq!(7, vec.capacity());

pub fn room(&self) -> usize

Returns the available room for new items; i.e., capacity() - len().

Examples

use orx_fixed_vec::prelude::*;

let mut vec = FixedVec::new(7);
vec.push(42);

assert_eq!(7, vec.capacity());
assert_eq!(1, vec.len());
assert_eq!(6, vec.room());

pub fn is_full(&self) -> bool

Return whether the fixed vector is full or not; equivalent to capacity() == len() or room() == 0.

Examples

use orx_fixed_vec::prelude::*;

let mut vec = FixedVec::new(2);
assert!(!vec.is_full());

vec.push(42);
assert!(!vec.is_full());

vec.push(7);
assert!(vec.is_full());

Trait Implementations

impl<T> AsMut<[T]> for FixedVec<T>

fn as_mut(&mut self) -> &mut [T]

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<[T]> for FixedVec<T>

fn as_ref(&self) -> &[T]

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Debug for FixedVec<T>where T: Debug,

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

Formats the value using the given formatter.

impl<T> From<FixedVec<T>> for Vec<T>

fn from(value: FixedVec<T>) -> Self

Converts to this type from the input type.

impl<T> From<Vec<T, Global>> for FixedVec<T>

fn from(value: Vec<T>) -> Self

Converts to this type from the input type.

impl<T, I> Index<I> for FixedVec<T>where I: SliceIndex<[T]>,

type Output = <I as SliceIndex<[T]>>::Output

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T, I> IndexMut<I> for FixedVec<T>where I: SliceIndex<[T]>,

fn index_mut(&mut self, index: I) -> &mut Self::Output

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

impl<T> IntoIterator for FixedVec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T, Global>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, U> PartialEq<U> for FixedVec<T>where U: AsRef<[T]>, T: PartialEq,

fn eq(&self, other: &U) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PinnedVec<T> for FixedVec<T>

fn index_of(&self, element: &T) -> Option<usize>

Returns the index of the element with the given reference. This method has O(1) time complexity.

Note that T: Eq is not required; reference equality is used.

Safety

Since FixedVec implements PinnedVec, the underlying memory of the vector stays pinned; i.e., is not carried to different memory locations. Therefore, it is possible and safe to compare an element’s reference to find its position in the vector.

Examples

use orx_fixed_vec::prelude::*;

let mut vec = FixedVec::new(4);
for i in 0..4 {
    vec.push(10 * i);
}

assert_eq!(Some(0), vec.index_of(&vec[0]));
assert_eq!(Some(1), vec.index_of(&vec[1]));
assert_eq!(Some(2), vec.index_of(&vec[2]));
assert_eq!(Some(3), vec.index_of(&vec[3]));

// the following does not compile since vec[4] is out of bounds
// assert_eq!(Some(3), vec.index_of(&vec[4]));

// num certainly does not belong to `vec`
let num = 42;
assert_eq!(None, vec.index_of(&num));

// even if its value belongs
let num = 20;
assert_eq!(None, vec.index_of(&num));

// as expected, querying elements of another vector will also fail
let eq_vec = vec![0, 10, 20, 30];
for i in 0..4 {
    assert_eq!(None, vec.index_of(&eq_vec[i]));
}

fn extend_from_slice(&mut self, other: &[T])where T: Clone,

Clones and appends all elements in a slice to the Vec.

Iterates over the slice other, clones each element, and then appends it to this Vec. The other slice is traversed in-order.

Note that this function is same as extend except that it is specialized to work with slices instead. If and when Rust gets specialization this function will likely be deprecated (but still available).

Panics

Panics if there is not enough room in the vector for the elements in other; i.e., self.room() < other.len().

fn push(&mut self, value: T)

Appends an element to the back of a collection.

Panics

Panics if there is no available room in the vector; i.e., self.is_full() or equivalently self.len() == self.capacity().

unsafe fn unsafe_insert(&mut self, index: usize, element: T)

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index >= len.

Panics also if there is no available room in the vector; i.e., self.is_full() or equivalently self.len() == self.capacity().

Safety

This operation is unsafe when T is not NotSelfRefVecItem. To pick the conservative approach, every T which does not implement NotSelfRefVecItem is assumed to be a vector item referencing other vector items.

insert is unsafe since insertion of a new element at an arbitrary position of the vector typically changes the positions of already existing elements.

When the elements are holding references to other elements of the vector, this change in positions makes the references invalid.

On the other hand, any vector implementing PinnedVec<T> where T: NotSelfRefVecItem implements PinnedVecSimple<T> which implements the safe version of this method.

fn clear(&mut self)

Clears the vector, removing all values.

fn capacity(&self) -> usize

Returns the total number of elements the vector can hold without reallocating.

fn get(&self, index: usize) -> Option<&T>

Returns a reference to an element with the given index, returns None if the index is out of bounds.

fn get_mut(&mut self, index: usize) -> Option<&mut T>

Returns a mutable reference to an element with the given index, returns None if the index is out of bounds.

unsafe fn get_unchecked(&self, index: usize) -> &T

Returns a reference to an element or subslice, without doing bounds checking.

unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T

Returns a mutable reference to an element or subslice, without doing bounds checking.

fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

fn len(&self) -> usize

Returns the number of elements in the vector, also referred to as its ‘length’.

unsafe fn unsafe_remove(&mut self, index: usize) -> T

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

unsafe fn unsafe_pop(&mut self) -> Option<T>

Removes the last element from a vector and returns it, or None if it is empty.

unsafe fn unsafe_swap(&mut self, a: usize, b: usize)

Swaps two elements in the slice.

unsafe fn unsafe_truncate(&mut self, len: usize)

Shortens the vector, keeping the first len elements and dropping the rest.

unsafe fn unsafe_clone(&self) -> Selfwhere T: Clone,

Creates and returns a clone of the vector.

fn partial_eq<S>(&self, other: S) -> boolwhere S: AsRef<[T]>, T: PartialEq,

This method tests for self and other values to be equal, and is used by ==.

fn debug(&self, f: &mut Formatter<'_>) -> Resultwhere T: Debug,

Formats the value using the given formatter.