ChunkedVec

Note: This is a learning project implementing a chunk-oriented vector collection with fixed-size chunk storage.

ChunkedVec is a chunk-oriented vector collection built around fixed-size chunk storage. It keeps familiar vector-style operations for individual elements while also exposing chunk-aware APIs for traversing and processing data chunk by chunk.

Features

Fixed-size chunk storage with compile-time or default chunk sizing
Chunk-oriented APIs such as chunk, first_chunk, last_chunk, and iter_chunks
Familiar vector-style interface with efficient element access and mutation
Support for both fixed-size and default-size chunk construction
O(1) random access time complexity
Efficient memory allocation during growth
Support for constructing from various types (Vec, Array, Slice, Iterator)

Usage Examples

Basic Usage with Default Chunk Size

use chunked_vec::ChunkedVec;

fn main() {
    let mut vec = ChunkedVec::new();
    vec.push(1);
    vec.push(2);
    vec.push(3);

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

Using Macro for Quick Initialization

use chunked_vec::{chunked_vec, ChunkedVec};

fn main() {
    // Create an empty ChunkedVec
    let vec: ChunkedVec<i32> = chunked_vec![];
    assert_eq!(vec.len(), 0);

    // Create a ChunkedVec with initial values
    let vec = chunked_vec![1, 2, 3, 4, 5];
    assert_eq!(vec[0], 1);

    // Create a ChunkedVec with repeated values
    let vec = chunked_vec![42; 5]; // [42, 42, 42, 42, 42]
    assert_eq!(vec.len(), 5);
}

Using Fixed Chunk Size

use chunked_vec::{ChunkedVec, ChunkedVecSized};

fn main() {
    // Create a ChunkedVec with chunk size of 8
    let mut vec: ChunkedVec<i32, 8> = ChunkedVecSized::new();
    vec.push(1);

    // Pre-allocate space for elements
    let vec = ChunkedVecSized::<i32, 8>::with_capacity(100);
    assert_eq!(vec.capacity(), 104);// Actual capacity of ChunkedVec rounds up to chunk size
}

Chunk-Oriented Access

use chunked_vec::{ChunkedVec, ChunkedVecSized};

fn main() {
    let mut vec: ChunkedVec<i32, 4> = ChunkedVecSized::new();
    vec.extend(0..10);

    assert_eq!(vec.chunk_size(), 4);
    assert_eq!(vec.chunk_count(), 3);
    assert_eq!(vec.first_chunk(), Some(&[0, 1, 2, 3][..]));
    assert_eq!(vec.last_chunk(), Some(&[8, 9][..]));

    for chunk in vec.iter_chunks_mut() {
        for value in chunk {
            *value += 1;
        }
    }

    assert_eq!(vec.chunk(1), Some(&[5, 6, 7, 8][..]));
}

Converting from Other Collections

use chunked_vec::ChunkedVec;

fn main() {
    // From Vec
    let vec = vec![1, 2, 3];
    let chunked: ChunkedVec<i32> = vec.into();

    // From array
    let arr = [1, 2, 3];
    let chunked = ChunkedVec::from(arr);

    // From slice
    let slice: &[i32] = &[1, 2, 3];
    let chunked = ChunkedVec::from(slice);

    // From iterator
    let chunked: ChunkedVec<i32> = (0..10).collect();
}

Current Implementation Status

Implemented Features

Comprehensive constructors (new, with_capacity, with_chunk_count)
Push operation (supports all types)
Index-based access (get, get_mut, Index/IndexMut traits)
Chunk-oriented access (chunk_size, chunk_count, chunk, chunk_mut, first_chunk, last_chunk)
Chunk iterators (iter_chunks, iter_chunks_mut)
Length and capacity queries (len, capacity, allocated_capacity)
Fixed-size chunk support via ChunkedVecSized
From/FromIterator implementations for various types
Safe and unsafe getter methods
Efficient memory management

Planned Features

Broader collection API coverage
Custom allocator support
More collection traits implementation
Performance optimizations for specific use cases

Contributing

This is an open learning project. Contributions and suggestions are welcome! Feel free to:

Report bugs and suggest features
Submit pull requests
Share your use cases and feedback
Help improve documentation

chunked_vec 0.5.0