Crate arrav

A sentinel-based, heapless, Vec-like type.

Arrays are great, because they do not require allocation. But arrays are fixed-size.

Slices are great, because you can make them smaller. But slices aren't Sized.

Vectors are great, because you can make them bigger. But vectors require allocation.

This type provides a type that acts like a vector but is represented exactly like an array. Unlike other array-backed vector-like types, but like C-style strings and arrays, Arrav uses a sentinel value (dictated by Sentinel) to indicate unoccupied elements. This makes push and pop a little slower, but avoids having to store the length separately. The trade-off is that the sentinel value can no longer be stored in the array.

Arrav is intended for when you have a small but variable number of small values that you want to store compactly (e.g., because they're going to be stored in a large number of elements). This is also why the "search" for the sentinel value to determine the array's length (and thus for push and pop) is unlikely to matter in practice.

Unlike C-style strings and arrays, which use NULL as the sentinel, Arrav uses the max value of the type (like std::u8::MAX). This means that unless you are saturating the type's range, you won't even notice the sentinel.

This crate uses the highly experimental const generics feature, and requires nightly.

Why the name? Arrav looks like the word "Array", but with "a bit chopped off".

Examples

use arrav::Arrav;
let mut av = Arrav::<_, 4>::new();
assert_eq!(av.capacity(), 4);
assert!(av.is_empty());

av.try_push(1).unwrap();
av.try_push(2).unwrap();
av.try_push(std::i32::MAX).unwrap_err();

assert_eq!(av.len(), 2);
assert_eq!(av[0], 1);

assert_eq!(av.pop(), Some(2));
assert_eq!(av.len(), 1);

av.set(0, 7).unwrap();
assert_eq!(av[0], 7);

av.extend([1, 2, 3].iter().copied());

for x in &av {
    println!("{}", x);
}
assert_eq!(av, [7, 1, 2, 3]);

assert_eq!(av.len(), av.capacity());
av.try_push(3).unwrap_err();

The avec! macro is provided to make initialization more convenient:

use arrav::avec;
let av = avec![1, 2, 3];
assert_eq!(av.capacity(), 3);
assert_eq!(av, [1, 2, 3]);

It can also initialize each element of a Arrav<T> with a given value. This may be more efficient than performing allocation and initialization in separate steps, especially when initializing a vector of zeros:

use arrav::{Arrav, avec};
let av = arrav::avec![0; 5];
assert_eq!(av, [0, 0, 0, 0, 0]);

// The following is equivalent, but potentially slower:
let mut av1: Arrav<_, 5> = Arrav::new();
av1.resize(5, 0);
assert_eq!(av, av1);

Modules

errors	Arrav error types.
iter	Arrav iterator types.

Macros

ArravOf	Produce an Arrav type that fits in a given container type.
avec	Creates a Arrav containing the arguments.

Structs

Arrav

A Vec-like type backed only by an array.

Traits

Sentinel

A type that has a sentinel value that can be used to indicate termination in Arrav.