Struct GenericVec 

#[repr(C)]
pub struct GenericVec<T, S: ?Sized + Storage<Item = T>> { /* private fields */ }

A vector type that can be backed up by a variety of different backends including slices, arrays, and the heap.

Implementations

impl<S: Storage> GenericVec<<S as Storage>::Item, S>

pub fn with_storage(storage: S) -> Self

Create a new empty GenericVec with the given backend

use cl_generic_vec::{ArrayVec, uninit_array};
let vec = ArrayVec::<i32, 4>::with_storage(uninit_array());

impl<S: StorageWithCapacity> GenericVec<<S as Storage>::Item, S>

pub fn with_capacity(capacity: usize) -> Self

Create a new empty GenericVec with the backend with at least the given capacity

impl<T, const N: usize> GenericVec<T, [MaybeUninit<T>; N]>

pub fn new() -> Self

Create a new empty ArrayVec

pub fn from_array(array: [T; N]) -> Self

Create a new full ArrayVec

pub fn into_array(self) -> [T; N]

Convert this ArrayVec into an array

Panics

Panics if the the collection is not full

pub fn try_into_array(self) -> Result<[T; N], Self>

Convert this ArrayVec into an array

Errors

errors if the the collection is not full

impl<T> GenericVec<T, Box<[MaybeUninit<T>]>>

pub fn new() -> Self

Available on crate feature alloc only.

Create a new empty HeapVec

impl<T, A: Allocator> GenericVec<T, Box<[MaybeUninit<T>], A>>

pub fn with_alloc(alloc: A) -> Self

Available on crate features nightly and alloc only.

Create a new empty HeapVec with the given allocator

impl<'a, T> GenericVec<T, &'a mut [MaybeUninit<T>]>

pub unsafe fn new(slice: &'a mut [MaybeUninit<T>]) -> Self

Create a new empty SliceVec.

Safety

The contents of the slice should be completely uninitialised

pub fn full(slice: &'a mut [T]) -> Self

Create a new full SliceVec

impl<S: Storage> GenericVec<<S as Storage>::Item, S>

pub fn into_raw_parts(self) -> (usize, S)

Convert a GenericVec into a length-storage pair

pub unsafe fn from_raw_parts(len: usize, storage: S) -> Self

Create a GenericVec from a length-storage pair

Safety

the length must be less than raw.capacity() and all elements in the range 0..length, must be initialized

Panic

If the given storage cannot hold type T, then this method will panic

impl<S: ?Sized + Storage> GenericVec<<S as Storage>::Item, S>

pub fn capacity(&self) -> usize

Returns the number of elements the vector can hold without reallocating or panicing.

pub fn is_empty(&self) -> bool

Returns true if and only if the vector contains no elements.

pub fn is_full(&self) -> bool

Returns true if and only if the vector’s length is equal to it’s capacity.

pub fn remaining_capacity(&self) -> usize

Returns the length of the spare capacity of the GenericVec

pub unsafe fn set_len_unchecked(&mut self, len: usize)

Set the length of a vector

Safety

• new_len must be less than or equal to capacity().
• The elements at old_len..new_len must be initialized.

pub unsafe fn set_len(&mut self, len: usize)

Set the length of a vector

Panics

If the length is set to be larger than the capacity

Safety

• The elements at old_len..new_len must be initialized.

pub fn as_slice(&self) -> &[S::Item]

Extracts a slice containing the entire vector.

Equivalent to &s[..].

pub fn as_mut_slice(&mut self) -> &mut [S::Item]

Extracts a mutable slice containing the entire vector.

Equivalent to &mut s[..].

pub fn storage(&self) -> &S

Returns the underlying storage

pub unsafe fn storage_mut(&mut self) -> &mut S

Returns the underlying storage

Safety

You must not replace the storage

pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<S::Item>]

Returns the remaining spare capacity of the vector as a SliceVec<'_, T>.

Keep in mind that the SliceVec<'_, T> will drop all elements that you push into it when it goes out of scope! If you want these modifications to persist then you should use save_spare to persist these writes.

let mut vec = cl_generic_vec::ArrayVec::<i32, 16>::new();

let mut spare = vec.spare_capacity_mut();
spare.push(0);
spare.push(2);
drop(spare);
assert_eq!(vec, []);

let mut spare = vec.spare_capacity_mut();
spare.push(0);
spare.push(2);
unsafe { cl_generic_vec::save_spare!(spare, &mut vec) }
assert_eq!(vec, [0, 2]);

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

Reserve enough space for at least additional elements

Panics

May panic or abort if it isn’t possible to allocate enough space for additional more elements

pub fn try_reserve(&mut self, additional: usize) -> AllocResult

Try to reserve enough space for at least additional elements

Errors

Returns Err(_) if it’s not possible to reserve enough space

pub fn truncate(&mut self, len: usize)

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

If len is greater than the vector’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the vector.

pub fn grow(&mut self, additional: usize, value: S::Item)

where S::Item: Clone,

Grows the GenericVec in-place by additional elements.

This method requires T to implement Clone, in order to be able to clone the passed value. If you need more flexibility (or want to rely on Default instead of Clone), use GenericVec::grow_with.

Panic

May panic or reallocate if the collection is full

Panic behavor

If T::clone panics, then all added items will be dropped. This is different from std, where on panic, items will stay in the Vec. This behavior is unstable, and may change in the future.

pub fn grow_with<F>(&mut self, additional: usize, value: F)

where F: FnMut() -> S::Item,

Grows the GenericVec in-place by additional elements.

This method uses a closure to create new values on every push. If you’d rather Clone a given value, use GenericVec::resize. If you want to use the Default trait to generate values, you can pass Default::default as the second argument.

Panic

May panic or reallocate if the collection is full

Panic behavor

If F panics, then all added items will be dropped. This is different from std, where on panic, items will stay in the Vec. This behavior is unstable, and may change in the future.

pub fn resize(&mut self, new_len: usize, value: S::Item)

where S::Item: Clone,

Resizes the GenericVec in-place so that len is equal to new_len.

If new_len is greater than len, the GenericVec is extended by the difference, with each additional slot filled with value. If new_len is less than len, the GenericVec is simply truncated.

If you know that new_len is larger than len, then use GenericVec::grow

If you know that new_len is less than len, then use GenericVec::truncate

This method requires T to implement Clone, in order to be able to clone the passed value. If you need more flexibility (or want to rely on Default instead of Clone), use GenericVec::resize_with.

Panic

May panic or reallocate if the collection is full

Panic behavor

If F panics, then all added items will be dropped. This is different from std, where on panic, items will stay in the Vec. This behavior is unstable, and may change in the future.

pub fn resize_with<F: FnMut() -> S::Item>(&mut self, new_len: usize, value: F)

Resizes the GenericVec in-place so that len is equal to new_len.

If new_len is greater than len, the GenericVec is extended by the difference, with each additional slot filled with the result of calling the closure f. The return values from f will end up in the GenericVec in the order they have been generated.

If new_len is less than len, the GenericVec is simply truncated.

If you know that new_len is larger than len, then use GenericVec::grow_with

If you know that new_len is less than len, then use GenericVec::truncate

This method uses a closure to create new values on every push. If you’d rather Clone a given value, use GenericVec::resize. If you want to use the Default trait to generate values, you can pass Default::default as the second argument.

Panic

May panic or reallocate if the collection is full

Panic behavor

If F panics, then all added items will be dropped. This is different from std, where on panic, items will stay in the Vec. This behavior is unstable, and may change in the future.

pub fn clear(&mut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

pub fn push(&mut self, value: S::Item) -> &mut S::Item

Appends an element to the back of a collection.

Panic

May panic or reallocate if the collection is full

pub fn push_array<const N: usize>( &mut self, value: [S::Item; N], ) -> &mut [S::Item; N]

Appends the array to the back of a collection.

Panic

May panic or reallocate if the collection has less than N elements remaining

pub fn insert(&mut self, index: usize, value: S::Item) -> &mut S::Item

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

Panics

• May panic or reallocate if the collection is full
• Panics if index > len.

pub fn insert_array<const N: usize>( &mut self, index: usize, value: [S::Item; N], ) -> &mut [S::Item; N]

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

Panics

• May panic or reallocate if the collection has less than N elements remaining
• Panics if index > len.

pub fn pop(&mut self) -> S::Item

Removes the last element from a vector and returns it

Panics

Panics if the collection is empty

pub fn pop_array<const N: usize>(&mut self) -> [S::Item; N]

Removes the last N elements from a vector and returns it

Panics

Panics if the collection contains less than N elements in it

pub fn remove(&mut self, index: usize) -> S::Item

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

Panics

Panics if index is out of bounds.

pub fn remove_array<const N: usize>(&mut self, index: usize) -> [S::Item; N]

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

Panics

Panics if index is out of bounds or if index + N > len()

pub fn swap_remove(&mut self, index: usize) -> S::Item

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Panics

Panics if index is out of bounds.

pub fn try_push(&mut self, value: S::Item) -> Result<&mut S::Item, S::Item>

Tries to append an element to the back of a collection.

Errors

Returns the Err(value) if the collection is full

Guaranteed to not panic/abort/allocate

pub fn try_push_array<const N: usize>( &mut self, value: [S::Item; N], ) -> Result<&mut [S::Item; N], [S::Item; N]>

Tries to append an array to the back of a collection. Returns the Err(value) if the collection doesn’t have enough remaining capacity to hold N elements.

Guaranteed to not panic/abort/allocate

pub fn try_insert( &mut self, index: usize, value: S::Item, ) -> Result<&mut S::Item, S::Item>

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

Errors

Returns the Err(value) if the collection is full or index is out of bounds

Guaranteed to not panic/abort/allocate

pub fn try_insert_array<const N: usize>( &mut self, index: usize, value: [S::Item; N], ) -> Result<&mut [S::Item; N], [S::Item; N]>

Inserts an array at position index within the vector, shifting all elements after it to the right. Returns the Err(value) if the collection doesn’t have enough remaining capacity to hold N elements or index is out of bounds

Guaranteed to not panic/abort/allocate

pub fn try_pop(&mut self) -> Option<S::Item>

Removes the last element from a vector and returns it, Returns None if the collection is empty

Guaranteed to not panic/abort/allocate

pub fn try_pop_array<const N: usize>(&mut self) -> Option<[S::Item; N]>

Removes the last N elements from a vector and returns it, Returns None if the collection is has less than N elements

Guaranteed to not panic/abort/allocate

pub fn try_remove(&mut self, index: usize) -> Option<S::Item>

Removes and returns the element at position index within the vector, shifting all elements after it to the left. Returns None if collection is empty or index is out of bounds.

Guaranteed to not panic/abort/allocate

pub fn try_remove_array<const N: usize>( &mut self, index: usize, ) -> Option<[S::Item; N]>

Removes and returns the element at position index within the vector, shifting all elements after it to the left. Returns None if the collection is has less than N elements or index is out of bounds.

Guaranteed to not panic/abort/allocate

pub fn try_swap_remove(&mut self, index: usize) -> Option<S::Item>

Removes an element from the vector and returns it. Returns None if collection is empty or index is out of bounds.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Guaranteed to not panic/abort/allocate

pub unsafe fn push_unchecked(&mut self, value: S::Item) -> &mut S::Item

Appends an element to the back of a collection.

Safety

the collection must not be full

pub unsafe fn push_array_unchecked<const N: usize>( &mut self, value: [S::Item; N], ) -> &mut [S::Item; N]

Appends the array to the back of a collection.

Safety

the collection’s remaining capacity must be at least N

pub unsafe fn insert_unchecked( &mut self, index: usize, value: S::Item, ) -> &mut S::Item

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

Safety

• the collection is must not be full
• the index must be in bounds

pub unsafe fn insert_array_unchecked<const N: usize>( &mut self, index: usize, value: [S::Item; N], ) -> &mut [S::Item; N]

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

Safety

• the collection’s remaining capacity must be at least N
• hte index must be in bounds

pub unsafe fn pop_unchecked(&mut self) -> S::Item

Removes the last element from a vector and returns it

Safety

the collection must not be empty

pub unsafe fn pop_array_unchecked<const N: usize>(&mut self) -> [S::Item; N]

Removes the last N elements from a vector and returns it

Safety

The collection must contain at least N elements in it

pub unsafe fn remove_unchecked(&mut self, index: usize) -> S::Item

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

Safety

the collection must not be empty, and index must be in bounds

pub unsafe fn remove_array_unchecked<const N: usize>( &mut self, index: usize, ) -> [S::Item; N]

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

Safety

the collection must contain at least N elements, and index must be in bounds

pub unsafe fn swap_remove_unchecked(&mut self, index: usize) -> S::Item

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Safety

the index must be in bounds

pub fn split_off<B>(&mut self, index: usize) -> GenericVec<S::Item, B>

where B: StorageWithCapacity<Item = S::Item>,

Splits the collection into two at the given index.

Returns a newly allocated vector containing the elements in the range [at, len). After the call, the original vector will be left containing the elements [0, at) with its previous capacity unchanged.

assert_eq!(vec, [1, 2, 3]);
assert_eq!(vec2, [4, 5, 6]);
vec.split_off_into(1, &mut vec2);
assert_eq!(vec, [1]);
assert_eq!(vec2, [4, 5, 6, 2, 3]);

Panics

If the index is out of bounds

pub fn split_off_into<B>( &mut self, index: usize, other: &mut GenericVec<S::Item, B>, )

where B: Storage<Item = S::Item> + ?Sized,

Splits the collection into two at the given index.

Appends the elements from the range [at, len) to other. After the call, the original vector will be left containing the elements [0, at) with its previous capacity unchanged.

assert_eq!(vec, [1, 2, 3]);
assert_eq!(vec2, [4, 5, 6]);
vec.split_off_into(1, &mut vec2);
assert_eq!(vec, [1]);
assert_eq!(vec2, [4, 5, 6, 2, 3]);

Panics

If the index is out of bounds

pub fn append<B: Storage<Item = S::Item> + ?Sized>( &mut self, other: &mut GenericVec<S::Item, B>, )

Moves all the elements of other into Self, leaving other empty.

Does not change the capacity of either collection.

assert_eq!(vec, [1, 2, 3]);
assert_eq!(vec2, [4, 5, 6]);
vec.append(&mut vec2);
assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
assert_eq!(vec2, []);

Panic

May panic or reallocate if the collection is full

pub fn convert<B: StorageWithCapacity<Item = S::Item>>( self, ) -> GenericVec<S::Item, B>

where S: Sized,

Convert the backing storage type, and moves all the elements in self to the new vector

pub fn raw_cursor<R>(&mut self, range: R) -> RawCursor<'_, S>

where R: RangeBounds<usize>,

Creates a raw cursor that can be used to remove elements in the specified range. Usage of RawCursor is unsafe because it doesn’t do any checks. RawCursor is meant to be a low level tool to implement fancier iterators, like GenericVec::drain, GenericVec::drain_filter, or GenericVec::splice.

Panic

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

pub fn cursor<R>(&mut self, range: R) -> Cursor<'_, S>

where R: RangeBounds<usize>,

Creates a cursor that can be used to remove elements in the specified range.

Panic

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

pub fn drain<R>(&mut self, range: R) -> Drain<'_, S>

where R: RangeBounds<usize>,

Creates a draining iterator that removes the specified range in the vector and yields the removed items.

When the iterator is dropped, all elements in the range are removed from the vector, even if the iterator was not fully consumed. If the iterator is not dropped (with mem::forget for example), it is unspecified how many elements are removed.

Panic

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

pub fn drain_filter<R, F>(&mut self, range: R, f: F) -> DrainFilter<'_, S, F>

where R: RangeBounds<usize>, F: FnMut(&mut S::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be removed.

If the closure returns true, then the element is removed and yielded. If the closure returns false, the element will remain in the vector and will not be yielded by the iterator.

Panic

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

pub fn splice<R, I>( &mut self, range: R, replace_with: I, ) -> Splice<'_, S, I::IntoIter>

where R: RangeBounds<usize>, I: IntoIterator<Item = S::Item>,

Creates a splicing iterator that replaces the specified range in the vector with the given replace_with iterator and yields the removed items. replace_with does not need to be the same length as range.

range is removed even if the iterator is not consumed until the end.

It is unspecified how many elements are removed from the vector if the Splice value is leaked.

The input iterator replace_with is only consumed when the Splice value is dropped

Panic

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

pub fn retain<F>(&mut self, f: F)

where F: FnMut(&mut S::Item) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(e) returns false. This method operates in place, visiting each element exactly once in the original order, and preserves the order of the retained elements.

pub unsafe fn extend_from_slice_unchecked(&mut self, slice: &[S::Item])

Shallow copies and appends all elements in a slice to the GenericVec.

Safety

• You must not drop any of the elements in slice
• There must be at least slice.len() remaining capacity in the vector

pub fn extend_from_slice(&mut self, slice: &[S::Item])

where S::Item: Clone,

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

Iterates over the slice other, clones each element, and then appends it to this GenericVec. The other vector 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).

Panic behavor

If T::clone panics, then all newly added items will be dropped. This is different from std, where on panic, newly added items will stay in the Vec. This behavior is unstable, and may change in the future.

pub fn clone_from(&mut self, source: &[S::Item])

where S::Item: Clone,

Replaces all of the current elements with the ones in the slice

equivalent to the following

vec.clear();
vec.extend_from_slice(&slice);

Panic

May try to panic/reallocate if there is not enough capacity for the slice

pub fn dedup_by<F>(&mut self, same_bucket: F)

where F: FnMut(&mut S::Item, &mut S::Item) -> bool,

Removes all but the first of consecutive elements in the vector satisfying a given equality relation.

The same_bucket function is passed references to two elements from the vector and must determine if the elements compare equal. The elements are passed in opposite order from their order in the slice, so if same_bucket(a, b) returns true, a is removed.

If the vector is sorted, this removes all duplicates.

pub fn dedup_by_key<F, K>(&mut self, key: F)

where F: FnMut(&mut S::Item) -> K, K: PartialEq,

Removes all but the first of consecutive elements in the vector that resolve to the same key.

If the vector is sorted, this removes all duplicates.

pub fn dedup<F, K>(&mut self)

where S::Item: PartialEq,

Removes all but the first of consecutive elements in the vector that resolve to the same key.

If the vector is sorted, this removes all duplicates.

Trait Implementations

impl<T, S: ?Sized + Storage<Item = T>> Drop for GenericVec<T, S>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, A: Allocator> From<GenericVec<T, Box<[MaybeUninit<T>], A>>> for Vec<T, A>

fn from(vec: HeapVec<T, A>) -> Self

Converts to this type from the input type.

impl<T, const N: usize> TryFrom<GenericVec<T, [MaybeUninit<T>; N]>> for [T; N]

type Error = GenericVec<T, [MaybeUninit<T>; N]>

The type returned in the event of a conversion error.

fn try_from(value: ArrayVec<T, N>) -> Result<Self, Self::Error>

Performs the conversion.