Crate fallible_vec

Expand description

Fallible allocation functions for the Rust standard library’s alloc::vec::Vec type.

These functions are designed to be usable with #![no_std], #[cfg(no_global_oom_handling)](see https://github.com/rust-lang/rust/pull/84266) enabled and Allocators (see https://github.com/rust-lang/wg-allocators).

By default this crate requires the nightly compiler, but the stable compiler can be used if all features are disabled (i.e., specifying default-features = false for the dependency).

Usage

The recommended way to add these functions to Vec is by adding a use declaration for the FallibleVec trait: use fallible_vec::FallibleVec:

use fallible_vec::{FallibleVec, try_vec};

let mut vec = try_vec![1, 2]?;
vec.try_push(3)?;
assert_eq!(vec, [1, 2, 3]);

These methods are “panic safe”, meaning that if a call to external code (e.g., an iterator’s next() method or an implementation of Clone::clone()) panics, then these methods will leave the Vec in a consistent state:

len() will be less than or equal to capacity().
Items in 0..len() will only be items originally in the Vec or items being added to the Vec. It will never include uninitialized memory, duplicated items or dropped items.
Items originally (but no longer) in the Vec or being added to (but not yet in) the Vec may be leaked.

The exact behavior of each method is specified in its documentations.

Completeness

NOTE: This API is incomplete, there are many more infallible functions on Vec which have not been ported yet.

Macros

try_vec
Creates a Vec containing the arguments.
try_vec_in
Creates a Vec containing the arguments with the provided allocator.

Traits

FallibleVec
Fallible allocation methods for Vec.
TryCollect
Fallible allocations equivalents for Iterator::collect.

Functions