Crate fixed_slice_vec
source · [−]Expand description
FixedSliceVec
is a dynamic length Vec with runtime-determined maximum capacity backed by a slice.
Overview
This library is focused on meeting the following, narrow use case:
no_std
: Rust programming without the std library.- No global allocator: No access to the
alloc
crate - Runtime capacity : Maximum possible items in a collection or maximum possible backing bytes of storage is unknown until runtime.
Getting Started
fixed-slice-vec
is a Rust library, built and tested via Cargo. It
has no dependencies outside of the Rust core library.
To add fixed-slice-vec
to your Rust project, add a dependency to it
in your Cargo.toml file.
fixed-slice-vec = "0.10.0"
Usage
FixedSliceVec
In your Rust project source code, you can create a FixedSliceVec a number of ways (see the project Rust API docs for details). The most common form of construction is from a slice of uninitialized bytes.
use fixed_slice_vec::FixedSliceVec;
use core::mem::MaybeUninit;
// Safe to construct arrays of uninitialized values.
let mut bytes: [MaybeUninit<u8>; 1024] = unsafe { MaybeUninit::uninit().assume_init() };
let byte_slice = &mut bytes[..512];
let mut vec: FixedSliceVec<f64> = FixedSliceVec::from_uninit_bytes(byte_slice);
assert_eq!(0, vec.len());
assert!(vec.capacity() >= 63, "The exact capacity will depend on source-slice alignment");
vec.try_push(2.7f64).expect("Ran out of capacity unexpectedly");
assert_eq!(1, vec.len());
vec.clear();
assert!(vec.is_empty());
single module
As a companion to FixedSliceVec
, the single
submodule provides
functions for working with individual Rust values backed by arbitrary
byte slices. See the API Docs for details and examples.
Comparison
Several other Vec
-like crates exist and should be considered
as possible alternatives to FixedSliceVec
.
- The standard library’s Vec has a runtime dynamic capacity backed by an allocator. This should probably be your first choice if you have access to an allocator.
- ArrayVec has a compile-time fixed capacity. It is widely used and available on stable.
- StaticVec has a compile-time fixed capacity. It uses recent const generic features and is currently nightly-only.
- SliceVec has runtime fixed capacity.
This is the closest in its target use case to
FixedSliceVec
. We only discovered it existed after developingFixedSliceVec
, so there’s some evidence of convergent design or needs. It appears largely unmaintained over the last few years, does not make use of the MaybeUninit pattern for handling uninitialized data in Rust, and does not drop items correctly in some cases. It does not support creating an instance from raw bytes and requiresDefault
elements for some operations.
License
Copyright 2020 Auxon Corporation, released under the Apache 2.0 license.
Re-exports
pub use crate::vec::*;