[−][src]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.
Semi-Important Tidbits
This crate uses the highly experimental const generics feature, and requires nightly.
The crate supports no_std
environments without alloc
. Just turn off the std
feature.
Wondering 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 |
|
iter |
|
Macros
ArravOf | Produce an |
avec | Creates a |
Structs
Arrav | A |
Traits
Sentinel | A type that has a sentinel value that can be used to indicate termination in |