reliakit_collections/
lib.rs

1//! Bounded and reliability-oriented collection types for Rust.
2//!
3//! `reliakit-collections` provides collection types with enforced size
4//! constraints. The bounds are expressed as const generic parameters and
5//! checked at construction time. Mutations that would violate the bounds
6//! return errors rather than panicking.
7//!
8//! # Types
9//!
10//! - [`BoundedVec<T, MIN, MAX>`] — an owned `Vec<T>` constrained to hold
11//!   between `MIN` and `MAX` elements inclusive.
12//! - [`BoundedMap<K, V, MIN, MAX>`] — an insertion-ordered key-value map with
13//!   unique keys and an enforced entry-count range.
14//! - [`BoundedSet<T, MIN, MAX>`] — an insertion-ordered set of unique elements
15//!   with an enforced count range.
16//! - [`RingBuffer<T>`] — a fixed-capacity circular buffer that overwrites the
17//!   oldest element when full (a rolling window that never fails to push).
18//!
19//! [`BoundedMap`] and [`BoundedSet`] are backed by a `Vec` and use linear scans
20//! for lookup, so they stay deterministic and dependency-free (no hashing or
21//! ordering machinery) and are meant for the small, bounded sizes their bounds
22//! describe.
23//!
24//! # Examples
25//!
26//! ```
27//! use reliakit_collections::BoundedVec;
28//!
29//! // A list that must have between 1 and 10 recipients
30//! type RecipientList = BoundedVec<String, 1, 10>;
31//!
32//! let mut recipients = RecipientList::new(vec!["alice@example.com".into()]).unwrap();
33//! recipients.push("bob@example.com".into()).unwrap();
34//! assert_eq!(recipients.len(), 2);
35//! ```
36//!
37//! Mutations that would violate bounds are rejected:
38//!
39//! ```
40//! use reliakit_collections::BoundedVec;
41//!
42//! let mut v = BoundedVec::<i32, 1, 2>::new(vec![1, 2]).unwrap();
43//! assert!(v.push(3).is_err()); // at capacity
44//! assert!(v.pop().is_ok());    // still above minimum
45//! assert!(v.pop().is_err());   // would go below minimum
46//! ```
47//!
48//! # Feature flags
49//!
50//! - `std` (default) enables `std::error::Error` for [`CollectionError`] and
51//!   implies `alloc`.
52//! - `alloc` enables [`BoundedVec`], which is backed by `Vec<T>`.
53//!
54//! # `no_std`
55//!
56//! The crate supports `no_std`. [`BoundedVec`] requires the `alloc` feature
57//! (enabled by default via `std`). The error types ([`CollectionError`],
58//! [`CollectionResult`]) are available without `alloc`.
59
60#![cfg_attr(not(feature = "std"), no_std)]
61#![forbid(unsafe_code)]
62#![warn(missing_docs)]
63
64#[cfg(feature = "alloc")]
65extern crate alloc;
66
67#[cfg(feature = "alloc")]
68mod bounded_map;
69#[cfg(feature = "alloc")]
70mod bounded_set;
71#[cfg(feature = "alloc")]
72mod bounded_vec;
73mod error;
74#[cfg(feature = "alloc")]
75mod ring_buffer;
76
77#[cfg(feature = "alloc")]
78pub use bounded_map::BoundedMap;
79#[cfg(feature = "alloc")]
80pub use bounded_set::BoundedSet;
81#[cfg(feature = "alloc")]
82pub use bounded_vec::BoundedVec;
83pub use error::{CollectionError, CollectionResult};
84#[cfg(feature = "alloc")]
85pub use ring_buffer::RingBuffer;
reliakit_collections/lib.rs

reliakit_collections/
lib.rs
