Struct BumpVec 

pub struct BumpVec<T, const N: usize> { /* private fields */ }

Implementations

impl<T, const N: usize> BumpVec<T, N>

pub const fn new() -> Self

Constructs a new, empty BumpVec.

The vector will not allocate until elements are pushed onto it.

Examples

use bumpish::BumpVec;

let vec = BumpVec::<i32, 0>::new();

pub fn with_capacity(cap: usize) -> Self

Constructs a new, empty BumpVec<T> with at least the specified capacity.

The vector will be able to hold at least capacity elements without new allocations. This method is allowed to allocate for more elements than capacity. If capacity is zero, the vector will not allocate.

If it is important to know the exact allocated capacity of a BumpVec, always use the capacity method after construction.

For BumpVec<T> where T is a zero-sized type, there will be no allocation and the capacity will always be usize::MAX.

Examples

let mut vec = BumpVec::<_, 0>::with_capacity(10);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without additional allocations...
let cap = vec.capacity();
for i in 0..cap {
    vec.push(i);
}
assert_eq!(vec.len(), cap);
assert_eq!(vec.capacity(), cap);

// ...but this will make the vector allocate a new chunk
vec.push(cap);
assert_eq!(vec.len(), cap + 1);
assert!(vec.capacity() > cap);

// A vector of a zero-sized type will always over-allocate, since no
// allocation is necessary
let vec_units = BumpVec::<(), 0>::with_capacity(10);
assert_eq!(vec_units.capacity(), usize::MAX);

pub const fn capacity(&self) -> usize

Returns the total number of elements the vector can hold without additional allocations.

Examples

let mut vec = BumpVec::<_, 0>::with_capacity(10);
vec.push(42);
assert!(vec.capacity() >= 10);

A vector with zero-sized elements will always have a capacity of usize::MAX:

#[derive(Clone)]
struct ZeroSized;

assert_eq!(std::mem::size_of::<ZeroSized>(), 0);
let vec = BumpVec::<ZeroSized, 0>::with_capacity(0);
assert_eq!(vec.capacity(), usize::MAX);

pub const fn len(&self) -> usize

Returns the number of elements in the vector.

Examples

let vec = BumpVec::<_, 0>::from([1, 2, 3]);
assert_eq!(vec.len(), 3);

pub const fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

Examples

let mut vec = BumpVec::<_, 1>::new();
assert!(vec.is_empty());

vec.push(1);
assert!(!vec.is_empty());

pub fn first(&self) -> Option<&T>

Returns a reference to the first element of the vector, or None if it is empty.

Examples

let mut vec = BumpVec::<_, 1>::new();
assert_eq!(None, vec.first());

vec.push(42);
assert_eq!(Some(&42), vec.first());

pub fn first_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the first element of the vector, or None if it is empty.

Examples

let mut vec = BumpVec::<_, 1>::new();
assert_eq!(None, vec.first_mut());

vec.push(1);
if let Some(first) = vec.first_mut() {
    *first = 5;
}
assert_eq!(vec.first(), Some(&5));

pub fn last(&self) -> Option<&T>

Returns the reference to last element of the vector, or None if it is empty.

Examples

let vec = BumpVec::<_, 1>::new();
assert_eq!(None, vec.last());

vec.push(1);
assert_eq!(Some(&1), vec.last());

pub fn last_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the last element of the vector, or None if it is empty.

Examples

let mut vec = BumpVec::<_, 1>::new();
assert_eq!(None, vec.last_mut());

vec.push(1);
if let Some(last) = vec.last_mut() {
    *last = 5;
}
assert_eq!(vec.last_mut(), Some(&mut 5));

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

Returns a reference to an element by the specified index, or None if the index is out of bounds.

Examples

let v = BumpVec::<_, 3>::from([10, 40, 30]);
assert_eq!(Some(&40), v.get(1));
assert_eq!(None, v.get(3));

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

Returns a mutable reference to an element (see get) or None if the index is out of bounds.

Examples

let mut v = BumpVec::<_, 3>::from([0, 1, 2]);

if let Some(elem) = v.get_mut(1) {
    *elem = 42;
}
assert_eq!(v, &[0, 42, 2]);

pub fn push(&self, value: T) -> &T

Appends an element to the vector returning a reference to it.

Panics

Panics if the global allocator cannot allocate a new chunk of memory.

Examples

let vec = BumpVec::<_, 3>::new();
let new_element = vec.push(3);

assert_eq!(new_element, &3);
assert_eq!(vec, [3]);

Time complexity

Takes amortized O(1) time. If the vector’s current chunk of memory is exhausted, it tries to use the cached one if it exists, otherwise it tries to allocate a new chunk.

If the new chunk of memory is too big, it tries to divide the capacity by two and allocate it again until it reaches the minimum capacity. If it does, it panics.

pub fn push_mut(&mut self, value: T) -> &mut T

Appends an element to the vector, returning a mutable reference to it.

Panics

Panics if there is no way to allocate memory for a new capacity.

Examples

let mut vec = BumpVec::<_, 0>::from([1, 2]);
let last = vec.push_mut(3);
assert_eq!(*last, 3);
assert_eq!(vec, [1, 2, 3]);

let last = vec.push_mut(3);
*last += 1;
assert_eq!(vec, [1, 2, 3, 4]);

Time complexity

Takes amortized O(1) time. If the vector’s current chunk of memory is exhausted, it tries to use the cached one if it exists, otherwise it tries to allocate a new chunk.

If the new chunk of memory is too big, it tries to divide the capacity by two and allocate it again until it reaches the minimum capacity. If it does, it panics.

pub fn push_with_mut<F>(&mut self, f: F) -> &mut T

where F: FnOnce() -> T,

Pre-allocate space for an element in this vector, initializes it using the closure, and returns a mutable reference to the new element.

Examples

let mut vec = BumpVec::<_, 0>::new();
let new_element = vec.push_with_mut(|| 3);

assert_eq!(new_element, &3);
assert_eq!(vec, [3]);

Time complexity

Takes amortized O(1) time. If the vector’s current chunk of memory is exhausted, it tries to use the cached one if it exists, otherwise it tries to allocate a new chunk.

If the new chunk of memory is too big, it tries to divide the capacity by two and allocate it again until it reaches the minimum capacity. If it does, it panics.

pub fn pop(&mut self) -> Option<T>

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

Examples

let mut vec = BumpVec::<_, 0>::from([1, 2, 3]);
assert_eq!(vec.pop(), Some(3));
assert_eq!(vec, [1, 2]);

pub fn pop_if(&mut self, predicate: impl FnOnce(&mut T) -> bool) -> Option<T>

Removes and returns the last element from a vector if the predicate returns true, or None if the predicate returns false or the vector is empty (the predicate will not be called in that case).

Examples

let mut vec = BumpVec::<_, 0>::from([1, 2, 3, 4]);
let pred = |x: &mut i32| *x % 2 == 0;

assert_eq!(vec.pop_if(pred), Some(4));
assert_eq!(vec, [1, 2, 3]);
assert_eq!(vec.pop_if(pred), None);

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

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 of the remaining elements, but is O(1).

Panics

Panics if index is out of bounds.

Examples

let mut v = BumpVec::<_, 0>::from(["foo", "bar", "baz", "qux"]);

assert_eq!(v.swap_remove(1), "bar");
assert_eq!(v[1], "qux");
assert_eq!(v, ["foo", "qux", "baz"]);

assert_eq!(v.swap_remove(0), "foo");
assert_eq!(v, ["baz", "qux"]);

pub fn clear(&mut self)

Clears the vector, dropping all elements.

This method leaves the biggest chunk of memory for future allocations.

The order of dropping elements is not defined.

Examples

let mut vec = BumpVec::<_, 3>::from([1, 2, 3]);

vec.clear();

assert!(vec.is_empty());
assert!(vec.capacity() > 0);

pub fn contains(&self, value: &T) -> bool

where T: PartialEq,

Returns true if the vector contains an element with the given value.

This operation is likely O(log n), but

Examples

let vec = BumpVec::<_, 1>::from([3, 8, 12]);
assert!(vec.contains(&8));
assert!(!vec.contains(&20));

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

Returns an iterator over the vector.

Examples

let vec = BumpVec::<_, 3>::from([1, 2, 4]);
let mut iterator = vec.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);

Since BumpVec allows to push new elements using immutable reference to itself, you can push during iteration. But iteration is running over elements existing at the moment creating the iterator. It guarantees that you won’t get infinite loop.

let vec = BumpVec::<_, 3>::from([1, 2, 4]);

for elem in vec.iter() {
    vec.push(*elem);
}
assert_eq!(vec.len(), 6);
assert_eq!(vec, [1, 2, 4, 1, 2, 4]);

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

Returns a mutable iterator over the vector.

Examples

let mut vec = BumpVec::<_, 3>::from([1, 2, 4]);

for elem in vec.iter_mut() {
    *elem *= 2;
}

assert_eq!(&vec, &[2, 4, 8]);

pub fn chunks(&self) -> ChunkIter<'_, T, N>

Returns an iterator over slices corresponding to the vestor’s memory chunks.

The iterator returns chunks that contain real elements. The empty chunks, that are used as preallocated space, are ignored.

Examples

let vec = BumpVec::<_, 3>::from([0, 1, 2]);
assert_eq!(vec.chunks().collect::<Vec<_>>(), [&[0, 1, 2]]);

// fill up the first chunk
for i in 3..vec.capacity() {
    vec.push(i);
}
assert_eq!(vec.chunks().count(), 1);

// create a new chunk
vec.push(42);
assert_eq!(vec.chunks().count(), 2);

pub fn chunks_mut(&mut self) -> ChunkIterMut<'_, T, N>

Returns an iterator over mutable slices corresponding to the vector’s memory chunks.

Examples

let mut vec = BumpVec::<_, 3>::from([0, 1, 2]);

let chunk = vec.chunks_mut().next().unwrap();
assert_eq!(chunk, [0, 1, 2]);
chunk[0] = 42;
assert_eq!(chunk, [42, 1, 2]);

Trait Implementations

impl<T, const N: usize> Clone for BumpVec<T, N>

where T: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, const N: usize> Debug for BumpVec<T, N>

where T: Debug,

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

Formats the value using the given formatter.

impl<T, const N: usize> Default for BumpVec<T, N>

fn default() -> Self

Creates an empty BumpVec.

The vector will not allocate until elements are pushed onto it.

impl<T, const N: usize> From<&[T]> for BumpVec<T, N>

where T: Clone,

fn from(slice: &[T]) -> Self

Creates a BumpVec<T> with a chunk big enough to contain N items and fills it by cloning slice’s items.

impl<T, const N: usize, const M: usize> From<&[T; M]> for BumpVec<T, N>

where T: Clone,

fn from(slice: &[T; M]) -> Self

Creates a BumpVec<T> with a chunk big enough to contain N items and fills it by cloning slice’s items.

impl<T, const N: usize> From<&mut [T]> for BumpVec<T, N>

where T: Clone,

fn from(slice: &mut [T]) -> Self

Creates a BumpVec<T> with a chunk big enough to contain N items and fills it by cloning slice’s items.

impl<T, const N: usize, const M: usize> From<&mut [T; M]> for BumpVec<T, N>

where T: Clone,

fn from(slice: &mut [T; M]) -> Self

Creates a BumpVec<T> with a chunk big enough to contain N items and fills it by cloning slice’s items.

impl<T, const N: usize, const M: usize> From<[T; M]> for BumpVec<T, N>

where T: Clone,

fn from(array: [T; M]) -> Self

Creates a BumpVec<T> with a chunk big enough to contain N items and fills it by cloning array’s items.

impl<T, const N: usize> FromIterator<T> for BumpVec<T, N>

where T: Clone,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T, const N: usize> Hash for BumpVec<T, N>

where T: Hash,

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T, const N: usize> Index<usize> for BumpVec<T, N>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T, const N: usize> IndexMut<usize> for BumpVec<T, N>

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

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

impl<'a, T, const N: usize> IntoIterator for &'a BumpVec<T, N>

type Item = &'a T

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, const N: usize> IntoIterator for &'a mut BumpVec<T, N>

type Item = &'a mut T

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize> IntoIterator for BumpVec<T, N>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T, N>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, U, const N: usize> PartialEq<&[U]> for BumpVec<T, N>

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<&[U; M]> for BumpVec<T, N>

where T: PartialEq<U>,

fn eq(&self, other: &&[U; M]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize> PartialEq<&mut [U]> for BumpVec<T, N>

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<&mut [U; M]> for BumpVec<T, N>

where T: PartialEq<U>,

fn eq(&self, other: &&mut [U; M]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize> PartialEq<[U]> for BumpVec<T, N>

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<[U; M]> for BumpVec<T, N>

where T: PartialEq<U>,

fn eq(&self, other: &[U; M]) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<BumpVec<U, M>> for &[T; N]

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<BumpVec<U, M>> for &mut [T; N]

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<BumpVec<U, M>> for [T; N]

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, U, const N: usize, const M: usize> PartialEq<BumpVec<U, M>> for BumpVec<T, N>

where T: PartialEq<U>,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T, const N: usize> Eq for BumpVec<T, N>

where T: Eq,

impl<T, const N: usize> Send for BumpVec<T, N>

where T: Send,