cds/lib.rs
1//! *cds* is a Collection of Optimized Data Structures.
2//!
3//! *cds* implements optimized data structures and their associated algorithms.
4//!
5//!
6//! # Design and Implementation Principles
7//!
8//! 1. **Tested** - for both correctness and performance
9//! 2. **Fast** - even if it requires `unsafe` Rust
10//! 3. **Secure** - do not unnecessarily hold a copy of (possibly sensitive) user data;
11//! allow wiping of unused memory
12//! 4. **No malloc** - avoid dynamic memory allocation where possible
13//! 5. **Compact** - allow small memory footprint
14//!
15//!
16//! # Fixed-Capacity Data Structures
17//!
18//! Fixed-capacity data structures can be allocated on stack.
19//! They do not allocate memory on the heap, and their capacity cannot be dynamically changed.
20//!
21//! * [`ArrayVec`] - a vector-like array
22//! * [`ArrayString`] - a string-like array
23//!
24//!
25//! # Hybrid-Capacity Data Structures
26//!
27//! Hybrid-capacity data structures use both local and heap capacity.
28//! They have some local capacity, which, if not exceeded, avoids heap allocation.
29//! Once the amount of needed capacity exceeds the local capacity, a heap
30//! allocation is made, existing data is copied to the heap, and the data structure continues its
31//! operation from there.
32//!
33//! * [`SmallVec`] - a vector with “small size” optimization
34//!
35//!
36//! # Optional Features
37//!
38//! * `alloc` - enables usage of the standard [`alloc`] crate
39//! * `std` - implies `alloc` and enables implementation of [`std`] traits which are not available
40//! in [`core`]. Without this feature the library is [`no_std`].
41//! * `arrayvec` - enables [`ArrayVec`]
42//! * `arraystring` - enables [`ArrayString`]
43//! * `smallvec` - implies `alloc` and enables [`SmallVec`]
44//!
45//! By default, all optional features are enabled. To build in `no_std` environment, or to avoid
46//! compilation of unneeded functionality, disable default features and cherry pick the required
47//! features explicitly.
48//!
49//! [`ArrayVec`]: crate::arrayvec::ArrayVec
50//! [`ArrayString`]: crate::arraystring::ArrayString
51//! [`SmallVec`]: crate::smallvec::SmallVec
52//! [`no_std`]: https://docs.rust-embedded.org/book/intro/no-std.html
53//!
54
55#![cfg_attr(not(feature = "std"), no_std)]
56#![warn(missing_docs)]
57#![cfg_attr(docsrs, feature(doc_cfg))]
58
59#[cfg(feature = "alloc")]
60extern crate alloc;
61
62#[cfg(feature = "arrayvec")]
63#[cfg_attr(docsrs, doc(cfg(feature = "arrayvec")))]
64pub mod arrayvec;
65
66#[cfg(feature = "arraystring")]
67#[cfg_attr(docsrs, doc(cfg(feature = "arraystring")))]
68pub mod arraystring;
69
70#[cfg(feature = "smallvec")]
71#[cfg_attr(docsrs, doc(cfg(feature = "smallvec")))]
72pub mod smallvec;
73
74pub mod len;
75pub mod mem;
76
77pub(crate) mod sealed;
78
79#[cfg(test)]
80#[cfg(not(tarpaulin_include))]
81pub(crate) mod testing;