1 unstable release

0.1.0 Dec 12, 2023

#1669 in Data structures

MPL-2.0 license

14KB
210 lines

Rustifact extras   Latest Version docs

In future, this crate may provide other extensions to Rustifact, but for now, it serves to provide jagged array support.

Motivation

Definition: A jagged array is an array with rows of uneven lengths.

Suppose we have a collections of arrays [T; N1], [T; N2]..., [T; Nn] that we wish to precalculate at compile time. We can store the elements in a Vec<Vec<T>>, or a [Vec<T>; n], but these are unsuitable for static memory.

The types JaggedArray and BareJaggedArray allow us to efficiently store jagged arrays in static memory by pre-populating them in a buildscript with Rustifact.

Types

  • JaggedArray provides indexing capability at compile time and runtime. Use this type if you're unsure of your requirements.
  • BareJaggedArray provides indexing capability at compile time. Indexes are injected into runtime as token streams.

A simple example

build.rs

use rustifact::ToTokenStream;
use rustifact_extra::JaggedArrayBuilder;

fn main() {
    let mut num_array = JaggedArrayBuilder::new();
    num_array.push(vec![1, 2, 3]);
    num_array.push(vec![4]);
    num_array.push(vec![5, 6]);
    rustifact::write_const!(NUM_ARRAY_LEN, usize, num_array.len());
    rustifact::write_const!(NUM_ARRAY_ELEMS_LEN, usize, num_array.elems_len());
    rustifact::write_static!(NUM_ARRAY, JaggedArray<i32, NUM_ARRAY_LEN, NUM_ARRAY_ELEMS_LEN>, &num_array);
}

src/main.rs

rustifact::use_symbols!(NUM_ARRAY, NUM_ARRAY_LEN, NUM_ARRAY_ELEMS_LEN);
use rustifact_extra::JaggedArray;

fn main() {
    assert_eq!(NUM_ARRAY[0], [1, 2, 3]);
    assert_eq!(NUM_ARRAY[1], [4]);
    assert_eq!(NUM_ARRAY[2], [5, 6]);
}

Cargo.toml

[package]
## ...

[build-dependencies]
rustifact = "0.9"
rustifact_extra = "0.1"

[dependencies]
rustifact = "0.9"
rustifact_extra = "0.1"

More examples

  • jagged Generate a JaggedArray and index it at runtime.

  • barejagged Generate a BareJaggedArray, index it at compile time, and access the indices at runtime.

Unsafe code

Unfortunately, the Rust ecosystem (as of late 2023) doesn't provide a mechanism for the creation of slices in compile-time context. Therefore, rustifact_extra does use a small amount unsafe code in its JaggedArray and BareJaggedArray implementations. Please note that the main rustifact crate makes no use of unsafe.

License

rustifact_extra is free software, and is released under the terms of the Mozilla Public License version 2.0. See LICENSE.

Dependencies

~0.5–1MB
~23K SLoC