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//! - [`vec::ArrayVec`] - A fixed-capacity vector backed by a stack-allocated array
13//! - [`ringbuf::RingBuf`] - A fixed-capacity circular/ring buffer for FIFO operations
14//!
15//! All types in this crate:
16//! - Do not perform heap allocation
17//! - Have a fixed maximum capacity determined at compile time
18//! - Work in `no_std` environments
19//! - Provide APIs similar to their standard library counterparts
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 like `Error` trait implementations
72//!
73//! # Performance Characteristics
74//!
75//! All operations have the same time complexity as their heap-allocated counterparts:
76//! - Push/pop: O(1)
77//! - Index access: O(1)
78//! - Iteration: O(n)
79//!
80//! However, these types avoid heap allocation overhead and have better cache locality
81//! since data is stored inline on the stack.
82
83#![no_std]
84
85pub mod ringbuf;
86pub mod vec;