Struct dst::FixedVec

pub struct FixedVec<T, S> { /* fields omitted */ }

Imitates a std::vec::Vec of a slice-based DST. All values have the same slice length, which allows random-access. Guarantied to store all values inline in the same allocation (sequentially), only using extra space for inherent alignment-padding. The trade-off is that the slice-lengths of the dynamically sized tail must all be the same, and is stored alongside the pointer to the allocation/length/capacity. Thus, this Vec is 4-words instead of 3-words.

Panics / Aborts

Any operation that may increase the capacity will abort if there is a failure to allocate, or panic if the usize math overflows beforehand.

Uses

If your application knows at compile-time the length of a slice, you should use Vec<(T, [S; LENGTH])>. Read no further.

However, the length may not be known until runtime. In this scenario, a Vec<(T, Vec<S>)> or Vec<(T, Box<[S]>)> should be used instead, the latter verifiably not wasting any space.

In the case of the length only known at runtime (like reading in columns of a .csv file), those solutions may show evidence of degraded performance from the random memory access patterns of said pointers. By opting to use this implementation, there is a guaranty that all of the data is contained in a single allocation, as-is the case of the constant-length slice. Some applications may receive a performance benefit by arranging the data in this way, while others may lose performance from the overhead of this implementation.

Usage

use dst::FixedVec;

let mut vec = FixedVec::<Option<&str>, usize>::new(4);
vec.push_default();
let item = vec.get(0).unwrap();
assert_eq!(item.value, None);
assert_eq!(item.tail, [0, 0, 0, 0]);

vec.push(Some("Name"), [1, 2, 3, 4].iter().copied());
let item = vec.get(1).unwrap();
assert_eq!(item.value, Some("Name"));
assert_eq!(item.tail, [1, 2, 3, 4]);

Implementations

impl<T, S> Vec<T, S>

pub fn new(slice_length: usize) -> Self

Creates a new Vec that can contain items where the tail length is as provided. Will not allocate until an item is inserted or capacity reserved.

pub fn capacity(&self) -> usize

Returns the maximum number of items before a reallocation is needed.

pub fn slice_length(&self) -> usize

Returns the length of the tail for any/all items.

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

Will insure it has enough space for the specified number of items, growing according to an internal criteria.

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

Will allocate exactly enough memory to insure it has enough space for the specified number of elements, or do nothing if it has already allocated enough.

pub fn push(&mut self, value: T, slice: impl IntoIterator<Item = S>)

Adds an item using an iterator containing at least enough values to populate the DST's slice.

Panics

Panics if the iterator has insufficient element count.

pub fn insert(
    &mut self,
    ix: usize,
    value: T,
    slice: impl IntoIterator<Item = S>
)

Inserts an item using an iterator containing at least enough values to populate the DST's slice.

Panics

Panics if the iterator has insufficient element count. Panics if any index lower than the one provided has no item.

pub fn pop(&mut self)

Removes the last inserted element as if it was immediately dropped.

Panics

Panics if there are no items.

pub fn pop_boxed(&mut self) -> Box<Handle<T, [S]>>

Removes the last inserted element and returns it.

Panics

Panics if there are no items.

pub fn pop_value(&mut self) -> T

Removes the last inserted element as if the slice part was immediately dropped, but returning the value.

Panics

Panics if there are no items.

pub fn is_empty(&self) -> bool

Checks if there are any items.

pub fn get(&self, ix: usize) -> Option<&Handle<T, [S]>>

Returns a reference, or None if out of bounds.

pub unsafe fn get_unchecked(&self, ix: usize) -> &Handle<T, [S]>

Returns a reference without bound-checking.

pub fn get_mut(&mut self, ix: usize) -> Option<&mut Handle<T, [S]>>

Returns a mutable reference, or None if out of bounds.

pub unsafe fn get_unchecked_mut(&mut self, ix: usize) -> &mut Handle<T, [S]>

Returns a mutable reference without bound-checking.

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

Returns an iterator that provides references.

pub fn iter_mut(&mut self) -> IterMut<'_, T, S>

Returns an iterator that provides mutable references.

pub fn remove(&mut self, ix: usize)

Items the item at the index, shifting any later items.

Panics

Panics if there is no item at the index.

pub fn remove_range(&mut self, range: impl RangeBounds<usize>)

Removes the range of items, shifting any later items.

Panics

Panics if any index as specified by a non-open bound in the range has no item.

pub fn remove_replace(&mut self, ix: usize)

Removes the item at the index, replacing it with the last item. This avoids excessive copies, but by reordering.

Panics

Panics if there is no item at the index.

pub fn remove_range_replace(&mut self, range: impl RangeBounds<usize>)

Removes the range of items, replacing them with items from the end. This avoids excessive copies, but by reordering.

Panics

Panics if any index as specified by a non-open bound in the range has no item.

pub fn remove_value(&mut self, ix: usize) -> T

Removes the item at index as if the slice part was immediately dropped, but returning the value.

Panics

Panics if there is no item at the index.

pub fn move_from(&mut self, other: &mut Self, range: impl RangeBounds<usize>)

This moves values from the specified Vec to this one.

Panics

Panics if the values in the other Vec do not have the same tail-length. Panics if any of the other's indexes as specified by a non-open bound in the range has no item.

impl<T, S: Default> Vec<T, S>

pub fn push_default_slice(&mut self, value: T) -> &mut Handle<T, [S]>

Appends at the end using default to populate the slice.

pub fn insert_default_slice(
    &mut self,
    ix: usize,
    value: T
) -> &mut Handle<T, [S]>

Inserts at the index using default to populate the slice.

Panics

Panics if any index lower than the one provided has no item.

impl<T: Default, S: Default> Vec<T, S>

pub fn push_default(&mut self) -> &mut Handle<T, [S]>

Appends at the end using default to populate the value and slice.

pub fn insert_default(&mut self, ix: usize) -> &mut Handle<T, [S]>

Inserts at the index using default to populate the value and slice.

Panics

Panics if any index lower than the one provided has no item.

Trait Implementations

impl<T: Copy, S: Copy> Clone for Vec<T, S>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, S: Debug> Debug for Vec<T, S>

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

Formats the value using the given formatter.

impl<T, S> Drop for Vec<T, S>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Eq, S: Eq> Eq for Vec<T, S>

impl<T: Hash, S: Hash> Hash for Vec<T, S>

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<'a, T, S> IntoIterator for &'a Vec<T, S>

type Item = &'a Handle<T, [S]>

The type of the elements being iterated over.

type IntoIter = Iter<'a, T, S>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, S> IntoIterator for &'a mut Vec<T, S>

type Item = &'a mut Handle<T, [S]>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T, S>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<TL: PartialEq<TR>, TR, SL: PartialEq<SR>, SR> PartialEq<Vec<TR, SR>> for Vec<TL, SL>

fn eq(&self, other: &Vec<TR, SR>) -> bool

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, S> Send for Vec<T, S> where
    Handle<T, S>: Send, 

impl<T, S> Sync for Vec<T, S> where
    Handle<T, S>: Sync,