Module vec

Support for generic vector structures containing a (generally) resizable, contiguous array of items.

Usage

Fixed storage

Vec instances may be allocated in fixed storage, a buffer which might be stored on the stack or statically.

use flex_alloc::{storage::byte_storage, vec::Vec};

let mut buf = byte_storage::<1024>();
let mut v = Vec::new_in(&mut buf);
v.push(22usize);

A fixed storage buffer may also be chained to an allocator, meaning that when the capacity of the buffer is exceeded, then the allocator will be used to obtain additional memory. For critical sections where the size of the input is variable but may often fit on the stack, this can help to eliminate costly allocations and lead to performance improvements.

use flex_alloc::{alloc::SpillAlloc, storage::array_storage, vec::Vec};

let mut buf = array_storage::<_, 100>();
let mut v = Vec::new_in(buf.spill_alloc());
v.extend(1..1000);

Custom allocators

Additional allocators may be defined by implementing the Allocator trait. The allocator-api2 flag also enables compatibility with allocator_api2::alloc::Allocator implementations. See examples/bumpalo/ for an demonstration integrating the bumpalo allocator.

zeroize integration

Integration with zeroize is implemented at the allocator level in order to ensure that all buffers are zeroized, including intermediate allocations produced when a Vec is resized. Vectors will implement zeroize::Zeroize and zeroize::ZeroizeOnDrop when appropriate.

use flex_alloc::vec::ZeroizingVec;

let v = ZeroizingVec::from([1, 2, 3]);

Fixed storage buffers may be wrapped in zeroize::Zeroizing. Allocations produced on overflow when SpillAlloc::spill_alloc is used will automatically be zeroized as well.

use flex_alloc::{alloc::SpillAlloc, storage::array_storage, vec::Vec};
use zeroize::Zeroizing;

let mut buf = Zeroizing::new(array_storage::<usize, 10>());
let v = Vec::new_in(buf.spill_alloc());

Inline vectors

Vec can support inline storage of the contained data. This may be appropriate when the maximum number of elements is known and the vector is not being passed around to other functions:

use flex_alloc::vec::InlineVec;

let v = InlineVec::<usize, 5>::from_iter([1, 2, 3, 4, 5]);

use flex_alloc::{storage::Inline, vec};

let v = vec![in Inline::<5>; 1, 2, 3, 4, 5];

Thin vectors

Like the thin-vec crate (but without compatibility with Gecko), vectors may be customized to use a pointer-sized representation with the capacity and length stored within the allocated memory.

Note that unlike with a standard Vec, an allocation is also required to store a collection of ZSTs (zero-sized types).

use flex_alloc::vec::ThinVec;

let v = ThinVec::<usize>::from(&[1, 2, 3, 4, 5]);

Custom index sizes and growth behavior

Vec may be parameterized to use an alternative index type and/or alternative growth pattern when memory consumption is a concern. The supported index types are u8, u16, u32, and usize (the default). The standard growth pattern is GrowDoubling, which matches the standard library behavior.

use flex_alloc::{
    alloc::Global,
    capacity::GrowDoubling,
    vec::{config::Custom, Vec}
};

type Cfg = Custom<Global, u8, GrowDoubling>;
let v = Vec::<usize, Cfg>::new();

Modules

• buffer
  Vec buffer types and trait definitions.
• config
  Vec configuration types and trait definitions.

Structs

• Drain
  A struct used for draining items from a Vec as an iterator.
• IntoIter
  A struct used for extracting all items from a Vec as an iterator.
• Splice
  A struct used to manage an active splice operation for a Vec instance
• Vec
  A structure containing a resizable, contiguous array of items

Functions

• from_array
  Create a Vec<T> from an array [T; N].
• from_array_in
  Create a Vec<T, C> from an array [T; N] and an instance of VecNewIn<T>.
• from_elem
  Create a Vec<T> from a cloneable element T and a count of the number of elements.
• from_elem_in
  Create a Vec<T, C> from a cloneable element T, a count of the number of elements, and an instance of VecNewIn<T>.

Type Aliases

• InlineVec
  A vector which stores its contained data inline, using no external allocation.
• ThinVec
  A vector which is pointer-sized, storing its capacity and length in the allocated buffer.
• ZeroizingVec
  A vector which automatically zeroizes its buffer when dropped.