planck_noalloc/lib.rs
1//! Stack-allocated data structures with similar APIs to heap-allocated types.
2//!
3//! This crate provides fixed-size, stack-allocated alternatives to common heap-allocated
4//! data structures from the standard library. These types are useful in environments where
5//! heap allocation is unavailable, restricted, or undesirable (such as embedded systems,
6//! kernels, interrupt handlers, or early boot code).
7//!
8//! # Overview
9//!
10//! The crate includes the following data structures:
11//!
12//! **Always available (no-alloc):**
13//! - [`vec::ArrayVec`] - A fixed-capacity vector backed by a stack-allocated array
14//! - [`ringbuf::RingBuf`] - A fixed-capacity circular/ring buffer for FIFO operations
15//!
16//! **With the `alloc` feature:**
17//! - [`smallvec::SmallVec`] - A vector that stores elements inline then spills to the heap
18//! - [`smallstr::SmallStr`] - A UTF-8 string backed by `SmallVec`
19//! - [`smallbytestr::SmallByteStr`] - A byte string backed by `SmallVec`
20//!
21//! # When to Use This Crate
22//!
23//! Use `planck-noalloc` when:
24//! - You're working in a `no_std` environment without an allocator
25//! - You need predictable memory usage and performance
26//! - You want to avoid heap fragmentation
27//! - You're in an interrupt handler or other restricted context
28//! - Maximum size is known at compile time
29//!
30//! # Examples
31//!
32//! ## Using `ArrayVec`
33//!
34//! ```
35//! use planck_noalloc::vec::ArrayVec;
36//!
37//! // Create a vector that can hold up to 5 elements on the stack
38//! let mut vec = ArrayVec::<i32, 5>::new();
39//!
40//! vec.push(1);
41//! vec.push(2);
42//! vec.push(3);
43//!
44//! assert_eq!(vec.len(), 3);
45//! assert_eq!(vec[0], 1);
46//!
47//! for value in vec.iter() {
48//! println!("{}", value);
49//! }
50//! ```
51//!
52//! ## Using `RingBuf`
53//!
54//! ```
55//! use planck_noalloc::ringbuf::RingBuf;
56//!
57//! // Create a ring buffer that can hold up to 7 elements (SIZE-1)
58//! let mut buf = RingBuf::<u8, 8>::new();
59//!
60//! buf.push(1);
61//! buf.push(2);
62//! buf.push(3);
63//!
64//! assert_eq!(buf.pop(), Some(1));
65//! assert_eq!(buf.pop(), Some(2));
66//! assert_eq!(buf.len(), 1);
67//! ```
68//!
69//! # Features
70//!
71//! - `std` (default): Enables std-specific features and implies `alloc`
72//! - `alloc`: Enables types that can spill to the heap (`SmallVec`, `SmallStr`, `SmallByteStr`)
73//!
74//! # Performance Characteristics
75//!
76//! All operations have the same time complexity as their heap-allocated counterparts:
77//! - Push/pop: O(1)
78//! - Index access: O(1)
79//! - Iteration: O(n)
80//!
81//! However, these types avoid heap allocation overhead and have better cache locality
82//! since data is stored inline on the stack.
83
84#![no_std]
85
86#[cfg(feature = "alloc")]
87extern crate alloc;
88
89pub mod ringbuf;
90pub mod vec;
91
92#[cfg(feature = "alloc")]
93pub mod smallvec;
94#[cfg(feature = "alloc")]
95pub mod smallstr;
96#[cfg(feature = "alloc")]
97pub mod smallbytestr;