pagedvector 0.1.0

A sparse paged vector with lazy page allocation.
Documentation
  • Coverage
  • 91.67%
    11 out of 12 items documented0 out of 11 items with examples
  • Size
  • Source code size: 25.4 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 424.8 kB This is the summed size of all files generated by rustdoc for all configured targets
  • ร˜ build duration
  • this release: 15s Average build duration of successful builds.
  • all releases: 7s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • evnekdev/pagedvector
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • evnekdev

๐Ÿ“ฆ pagedvector (early experimental crate)

A lightweight Rust crate implementing a paged virtual vector optimized for sparse data.

It mimics how operating systems manage memory: instead of allocating a full vector, it only allocates memory for portions ("pages") that actually contain non-default values.


๐Ÿš€ Features

  • ๐Ÿ’พ Memory-efficient for sparse data
  • ๐Ÿ“„ Fixed-size paging system
  • โšก Lazy allocation (allocate on write)
  • ๐Ÿงน Automatic deallocation when using set()
  • ๐Ÿ” Familiar API (get, set, indexing)
  • ๐Ÿ“ฆ Serialization support (serde, bincode)

๐Ÿง  Concept

Instead of storing a full vector of size N, PagedVec:

  1. Splits the vector into equal-sized pages
  2. Stores pages as Option<Page<T>>
  3. Allocates a page only when needed
  4. Deallocates when all values return to default

๐Ÿ›  Example

use pagedvector::PagedVec;

fn main() {
    let mut vec = PagedVec::new(1_000_000, 0u32, 1024);

    // No memory allocated yet
    assert_eq!(vec.number_pages_alloc(), 0);

    // Write value
    vec.set(42, 100);

    // Now one page is allocated
    assert!(vec.number_pages_alloc() > 0);

    // Read values
    assert_eq!(vec[42], 100);
    assert_eq!(vec[43], 0);

    // Reset to default
    vec.set(42, 0);
}

๐Ÿ“š API

Create

let vec = PagedVec::new(length, default_value, page_size);

Access

vec.get(i);
vec.set(i, val);
vec[i];

Modify

vec.set(i, value);

Inspect

vec.len();
vec.is_default(i);
vec.number_pages_total();
vec.number_pages_alloc();

โš ๏ธ Notes

  • Requires T: Clone + PartialEq
  • Uses assert! for bounds (panics if invalid index)
  • Performance depends on page_size

๐Ÿ’ก Use Cases

  • Sparse arrays
  • Simulations
  • Game worlds
  • Scientific data
  • Memory-constrained environments

RoadMap

Implement more methods to get Vec<T>-like feel:

  • is_empty()

  • page_size()

  • capacity_pages()

  • clear()

  • fill(value)

  • contains(&value)

  • get(index) -> Option<&T>

  • get_mut(index) -> Option<&mut T>

  • v[i] // panics

  • v.get(i) // returns Option

  • iter()

  • iter_mut()

  • enumerate_non_default()

  • count_non_default()

  • allocated_pages()

  • deallocate_empty_pages()

  • resize(new_len, default)

  • truncate(new_len)

  • push(value)

  • pop()

  • extend(iter)

  • Default

  • From<Vec>

  • FromIterator

  • Extend

  • IntoIterator

  • is_allocated(index) -> bool

  • is_page_allocated(page_index) -> bool

  • page_index(index) -> usize

  • page_offset(index) -> usize

  • allocated_page_indices()

  • non_default_len()

  • sparsity()

  • memory_len_allocated()

  • allocated_fraction()

  • default_fraction()

  • to_vec()

  • into_vec()

  • from_vec(vec, default, psize)

  • shrink_pages()

  • recount_page(page_index)

  • recount_all_pages()

  • deallocate_default_pages()


๐Ÿ“ฆ Dependencies

serde = { version = "1", features = ["derive"] }
bincode = "2"

๐Ÿ“„ License

MIT License (see LICENSE file)