Struct ChunkedVec 

pub struct ChunkedVec<T, const N: usize = { crate::DEFAULT_CHUNK_SIZE }> { /* private fields */ }

A vector-like container that stores elements in fixed-size chunks, providing efficient memory allocation and element access.

ChunkedVec is designed to balance memory usage and performance by storing elements in fixed-size chunks rather than a single contiguous array. This approach can reduce memory fragmentation and improve performance for certain operations.

Type Parameters

• T: The type of elements to store. Can be any type that satisfies the required trait bounds.
• N: The size of each chunk (default: 64). This constant determines how many elements are stored in each internal chunk. Larger chunks may improve cache locality but increase memory overhead for partially filled chunks.

Internal Structure

• Elements are stored in a series of fixed-size chunks, each containing exactly N elements
• The chunks are managed by a Vec<Chunk<T, N>>, where each Chunk is a boxed array
• The total number of elements is tracked separately from the chunk storage

Examples

use chunked_vec::ChunkedVec;

// Create a new ChunkedVec with default chunk size
let mut vec = ChunkedVec::new();

// Add elements
vec.push(1);
vec.push(2);

// Access elements
assert_eq!(vec[0], 1);
assert_eq!(vec[1], 2);
assert_eq!(vec.len(), 2);

Implementations

impl<T> ChunkedVec<T>

Implementation of basic creation methods for ChunkedVec with default chunk size.

This implementation provides convenient methods to create ChunkedVec instances using the default chunk size (64). These methods are more flexible as they don’t require specifying the chunk size at compile-time, making them suitable for general use cases.

pub fn new() -> Self

Creates a new empty ChunkedVec with the default chunk size.

This is the most straightforward way to create a ChunkedVec when you don’t need a specific chunk size. The default chunk size is optimized for general use cases.

Examples

use chunked_vec::ChunkedVec;
let vec: ChunkedVec<i32> = ChunkedVec::new();

pub fn with_capacity(capacity: usize) -> Self

Creates an empty ChunkedVec with the specified capacity.

The actual number of chunks allocated will be calculated as ceiling(capacity / N), where N is the default chunk size.

Arguments

• capacity - The minimum number of elements the ChunkedVec should be able to hold

Examples

use chunked_vec::ChunkedVec;
let vec: ChunkedVec<i32> = ChunkedVec::with_capacity(10);

pub fn with_chunk_count(chunk_count: usize) -> Self

Creates an empty ChunkedVec with a fixed chunk size of N and the specified number of chunks.

The total capacity will be N * chunk_count.

Arguments

• chunk_count - The number of chunks to pre-allocate

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::with_chunk_count(2);
// This will allocate 2 chunks with total capacity of 16

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

Implementation of indexing operations for ChunkedVec.

This implementation provides various methods for accessing elements in the ChunkedVec, including safe and unsafe access methods, as well as implementations of the Index and IndexMut traits for convenient array-style access.

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

Returns a reference to an element without performing bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior.

Arguments

• index - The index of the element to access

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

Returns a mutable reference to an element without performing bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior.

Arguments

• index - The index of the element to access

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

Returns a reference to an element at the given index.

Returns None if the index is out of bounds.

Arguments

• index - The index of the element to access

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::new();
vec.push(1);
assert_eq!(vec.get(0), Some(&1));
assert_eq!(vec.get(1), None);

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

Returns a mutable reference to an element at the given index.

Returns None if the index is out of bounds.

Arguments

• index - The index of the element to access

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::new();
vec.push(1);
if let Some(x) = vec.get_mut(0) {
    *x = 10;
}
assert_eq!(vec[0], 10);

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

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

Returns an iterator over the elements of the vector.

The iterator yields all items from start to end.

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::new();
vec.push(1);
vec.push(2);

let mut sum = 0;
for element in vec.iter() {
    sum += *element;
}
assert_eq!(sum, 3);

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

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

Returns an iterator that allows modifying each element in the vector.

The iterator yields all items from start to end.

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::new();
vec.push(1);
vec.push(2);

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

assert_eq!(vec[0], 2);
assert_eq!(vec[1], 4);

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

Implementation of basic operations for ChunkedVec.

This implementation provides core vector operations such as pushing elements, querying length and capacity, and managing the internal chunk structure.

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

Appends an element to the back of the vector.

If the current chunk is full, a new chunk will be allocated to store the element. The element is always added to the end of the vector.

Arguments

• value - The value to push onto the vector

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::new();
vec.push(1);
assert_eq!(vec.len(), 1);

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

where T: Clone,

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

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

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 [ChunkedVec::resize_with]. If you only need to resize to a smaller size, use Vec::truncate.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<&str>::new();
vec.resize(3, "example");
let len = vec.len();
assert_eq!(len, 3);

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

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

Removes an element from the ChunkedVec and returns it.

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

This does not preserve ordering of the remaining elements, but is O(1). If you need to preserve the element order, use remove instead.

Panics

Panics if index is out of bounds.

Examples

use chunked_vec::chunked_vec;
let mut v = chunked_vec!["foo", "bar", "baz", "qux"];

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

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

pub fn len(&self) -> usize

Returns the number of elements in the vector.

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::new();
assert_eq!(vec.len(), 0);
vec.push(1);
assert_eq!(vec.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

Examples

use chunked_vec::ChunkedVec;
let mut vec = ChunkedVec::<i32>::new();
assert!(vec.is_empty());
vec.push(1);
assert!(!vec.is_empty());

pub fn capacity(&self) -> usize

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

The capacity is always a multiple of the chunk size N.

Examples

use chunked_vec::{ChunkedVecSized, ChunkedVec};
let vec: ChunkedVec<i32, 4> = ChunkedVecSized::with_capacity(10);
assert!(vec.capacity() >= 12); // Rounds up to multiple of chunk size

pub fn allocated_capacity(&self) -> usize

Returns the number of elements that can be held in currently allocated chunks.

This differs from capacity() in that it only counts space in chunks that have already been allocated, not potential space in the underlying Vec’s capacity.

Examples

use chunked_vec::{ChunkedVecSized, ChunkedVec};
let mut vec: ChunkedVec<i32, 4> = ChunkedVecSized::new();
vec.push(1);
assert_eq!(vec.allocated_capacity(), 4); // One chunk allocated

Trait Implementations

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

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

Formats the value using the given formatter.

impl<T> Default for ChunkedVec<T>

Implementation of the Default trait for ChunkedVec.

This implementation provides a way to create an empty ChunkedVec using the default() method. The created vector will use the default chunk size (64) and have no pre-allocated chunks.

Examples

use chunked_vec::ChunkedVec;
let vec: ChunkedVec<i32> = ChunkedVec::default();
assert!(vec.is_empty());

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize> Drop for ChunkedVec<T, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, const N: usize> Extend<T> for ChunkedVec<T, N>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: Clone> From<&[T]> for ChunkedVec<T>

Implements conversion from slices to ChunkedVec<T>.

This implementation creates a new ChunkedVec by cloning elements from the slice. The original slice remains unchanged and available for further use.

Examples

use chunked_vec::ChunkedVec;

let slice: &[i32] = &[1, 2, 3];
let chunked_vec = ChunkedVec::from(slice);
assert_eq!(chunked_vec[0], 1);

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

Converts to this type from the input type.

impl<T: Clone, const M: usize> From<&[T; M]> for ChunkedVec<T>

Implements conversion from references to fixed-size arrays to ChunkedVec<T>.

This allows creating a ChunkedVec from a reference to any array of known size M. The conversion preserves the order of elements.

Examples

use chunked_vec::ChunkedVec;

let array = &[1, 2, 3];
let chunked_vec = ChunkedVec::from(array);
assert_eq!(chunked_vec[0], 1);

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

Converts to this type from the input type.

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

Implements conversion from fixed-size arrays to ChunkedVec<T>.

This allows creating a ChunkedVec from any array of known size M. The conversion preserves the order of elements.

Examples

use chunked_vec::ChunkedVec;

let array = [1, 2, 3];
let chunked_vec = ChunkedVec::from(array);
assert_eq!(chunked_vec[0], 1);

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

Converts to this type from the input type.

impl<T> From<Vec<T>> for ChunkedVec<T>

Implements conversion from Vec<T> to ChunkedVec<T>.

This implementation efficiently converts a standard vector into a ChunkedVec by consuming the original vector and reusing its memory allocation when possible.

Examples

use chunked_vec::ChunkedVec;

let vec = vec![1, 2, 3];
let chunked_vec = ChunkedVec::from(vec);
assert_eq!(chunked_vec[0], 1);

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

Converts to this type from the input type.

impl<T> FromIterator<T> for ChunkedVec<T>

Implements the FromIterator trait for ChunkedVec, allowing it to be created from any iterator.

This implementation provides an efficient way to collect elements from an iterator into a ChunkedVec. It pre-allocates space based on the iterator’s size hint when available, which can improve performance by reducing the number of reallocations.

Examples

use chunked_vec::ChunkedVec;

let vec = vec![1, 2, 3, 4, 5];
let chunked_vec: ChunkedVec<_> = vec.into_iter().collect();
assert_eq!(chunked_vec.len(), 5);

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

Creates a value from an iterator.

impl<T, const N: usize> Index<usize> for ChunkedVec<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 ChunkedVec<T, N>

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

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

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

Implementation of IntoIterator for ChunkedVec, enabling use in for loops.

This implementation consumes the ChunkedVec, taking ownership of its elements.

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, const N: usize, const M: usize> PartialEq<[T; M]> for ChunkedVec<T, N>

where T: PartialEq,

fn eq(&self, other: &[T; 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.