fixed_slice_vec/
lib.rs

1//! `FixedSliceVec` is a dynamic length Vec with runtime-determined maximum capacity backed by a slice.
2//!
3//! ## Overview
4//!
5//! This library is focused on meeting the following, narrow use case:
6//! * **`no_std`** : Rust programming without the std library.
7//! * **No global allocator**: No access to the `alloc` crate
8//! * **Runtime capacity** : Maximum possible items in a collection or maximum
9//! possible backing bytes of storage is unknown until runtime.
10//!
11//! ## Getting Started
12//!
13//! `fixed-slice-vec` is a Rust library, built and tested via Cargo. It
14//! has no dependencies outside of the Rust core library.
15//!
16//! To add `fixed-slice-vec` to your Rust project, add a dependency to it
17//! in your Cargo.toml file.
18//!
19//! ```toml
20//! fixed-slice-vec = "0.10.0"
21//! ```
22//!
23//! ## Usage
24//!
25//! ### FixedSliceVec
26//!
27//! In your Rust project source code, you can create a FixedSliceVec a number of
28//! ways (see the project Rust API docs for details).
29//! The most common form of construction is from a slice of uninitialized bytes.
30//!
31//! ```rust
32//! use fixed_slice_vec::FixedSliceVec;
33//! use core::mem::MaybeUninit;
34//! // Safe to construct arrays of uninitialized values.
35//! let mut bytes: [MaybeUninit<u8>; 1024] = unsafe { MaybeUninit::uninit().assume_init() };
36//! let byte_slice = &mut bytes[..512];
37//! let mut vec: FixedSliceVec<f64> = FixedSliceVec::from_uninit_bytes(byte_slice);
38//!
39//! assert_eq!(0, vec.len());
40//! assert!(vec.capacity() >= 63, "The exact capacity will depend on source-slice alignment");
41//!
42//! vec.try_push(2.7f64).expect("Ran out of capacity unexpectedly");
43//! assert_eq!(1, vec.len());
44//!
45//! vec.clear();
46//! assert!(vec.is_empty());
47//! ```
48//!
49//! ### single module
50//!
51//! As a companion to `FixedSliceVec`, the `single` submodule provides
52//! functions for working with individual Rust values backed by arbitrary
53//! byte slices. See the API Docs for details and examples.
54//!
55//! ### Comparison
56//!
57//! Several other `Vec`-like crates exist and should be considered
58//! as possible alternatives to `FixedSliceVec`.
59//!
60//! * The standard library's [Vec](https://doc.rust-lang.org/std/vec/struct.Vec.html)
61//! has a runtime dynamic capacity backed by an allocator. This should probably
62//! be your first choice if you have access to an allocator.
63//! * [ArrayVec](https://crates.io/crates/arrayvec) has a compile-time
64//! fixed capacity. It is widely used and available on stable.
65//! * [StaticVec](https://crates.io/crates/staticvec) has a compile-time
66//! fixed capacity. It uses recent const generic features and is currently
67//! nightly-only.
68//! * [SliceVec](https://crates.io/crates/slicevec) has runtime fixed capacity.
69//! This is the closest in its target use case to `FixedSliceVec`. We
70//! only discovered it existed after developing `FixedSliceVec`, so there's some
71//! evidence of convergent design or needs. It appears largely
72//! unmaintained over the last few years, does not make use of the
73//! [MaybeUninit](https://doc.rust-lang.org/std/mem/union.MaybeUninit.html)
74//! pattern for handling uninitialized data in Rust, and does not drop items
75//! correctly in some cases. It does not support creating an instance from raw bytes
76//! and requires `Default` elements for some operations.
77//!
78//!
79//! ## License
80//!
81//! Copyright 2020 Auxon Corporation, released under the [Apache 2.0 license](./LICENSE).
82#![no_std]
83#![deny(warnings)]
84#![deny(missing_docs)]
85#![deny(clippy::all)]
86
87pub mod single;
88pub mod vec;
89
90pub use crate::vec::*;
fixed_slice_vec/lib.rs

fixed_slice_vec/
lib.rs
