refraction_types/lib.rs
1//! # refraction-types
2//!
3//! A zero-dependency, fixed-capacity ring buffer for networking and protocol parsing.
4//!
5//! This crate centers around [`BoundedRingBuffer<T>`], a bounded queue with
6//! overwrite-on-full semantics and a byte-oriented API for network payloads.
7//!
8//! ## Why This Exists
9//!
10//! This crate was extracted from transport-layer and Redis-like data flow work.
11//! The goal was to have a simple, fast, dependency-free structure tuned for
12//! network transmission and buffered data handling. Existing crates did not
13//! provide enough control over flow behavior, so this crate was split out to be
14//! reusable across future projects and to evolve into something more general.
15//!
16//! ## Why This Crate
17//!
18//! - Deterministic memory usage: capacity is fixed at construction time.
19//! - Predictable behavior under pressure: newest writes are kept, oldest data is dropped.
20//! - Fast typed reads/writes on `u8` buffers for frame/header parsing.
21//! - No external runtime dependencies.
22//!
23//! ## Core Semantics
24//!
25//! - [`BoundedRingBuffer::enqueue`] pushes one element to the tail.
26//! - [`BoundedRingBuffer::dequeue`] pops one element from the head.
27//! - If full, `enqueue` advances the head first (oldest item is discarded).
28//! - [`BoundedRingBuffer::front`] returns the oldest readable element.
29//! - [`BoundedRingBuffer::back`] returns the newest written element.
30//! - [`BoundedRingBuffer::advance`] reserves/advances write position by `n` slots and
31//! applies the same overwrite semantics.
32//!
33//! ## Quick Start
34//!
35//! ```
36//! use refraction_types::ring_buffer::BoundedRingBuffer;
37//!
38//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(4);
39//! rb.enqueue(10);
40//! rb.enqueue(20);
41//! rb.enqueue(30);
42//!
43//! assert_eq!(rb.front(), Some(&10));
44//! assert_eq!(rb.back(), Some(&30));
45//! assert_eq!(rb.dequeue(), Some(10));
46//! assert_eq!(rb.len(), 2);
47//! ```
48//!
49//! ## Overwrite-On-Full Example
50//!
51//! ```
52//! use refraction_types::ring_buffer::BoundedRingBuffer;
53//!
54//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(3);
55//! rb.enqueue_slice(&[1, 2, 3]);
56//! rb.enqueue(4); // overwrites 1
57//!
58//! let mut out = [0_u8; 3];
59//! let read = rb.dequeue_slice(&mut out, 3);
60//! assert_eq!(read, 3);
61//! assert_eq!(out, [2, 3, 4]);
62//! ```
63//!
64//! ## Typed Byte API (`BoundedRingBuffer<u8>`)
65//!
66//! `BoundedRingBuffer<u8>` exposes methods like `enqueue_u16`, `peek_i64`, and
67//! `dequeue_f32`. All numeric conversions use **big-endian** representation.
68//!
69//! ```
70//! use refraction_types::ring_buffer::BoundedRingBuffer;
71//!
72//! let mut rb = BoundedRingBuffer::<u8>::with_capacity(16);
73//! rb.enqueue_u16(0xCAFE);
74//! rb.enqueue_i32(-7);
75//!
76//! assert_eq!(rb.peek_u16(), Some(0xCAFE));
77//! assert_eq!(rb.dequeue_u16(), Some(0xCAFE));
78//! assert_eq!(rb.dequeue_i32(), Some(-7));
79//! ```
80//!
81//! ## Iteration
82//!
83//! Use [`BoundedRingBuffer::iter`] and [`BoundedRingBuffer::iter_mut`] to traverse
84//! readable elements in logical queue order, regardless of internal wrap-around.
85//!
86//! ## Modules
87//!
88//! - [`ring_buffer`]: core type and queue operations.
89//! - [`ring_specialization`]: typed big-endian helpers for `BoundedRingBuffer<u8>`.
90//! - [`ring_iter`]: iterator wrapper types.
91//! - [`ring_traits`]: trait implementations (`Display`, `Default`, `Extend`, etc.).
92//!
93//! ## Notes
94//!
95//! - `T` must implement `Copy + Default`.
96//! - `with_capacity(0)` panics by design.
97//! - `dequeue_slice` panics if output buffer is smaller than requested dequeue size.
98
99/// Default capacity used by [`ring_buffer::BoundedRingBuffer::new`].
100pub const BOUNDED_RING_BUFFER_DEFAULT_SIZE: usize = 65_535;
101
102pub mod ring_buffer;
103pub mod ring_iter;
104pub mod ring_specialization;
105pub mod ring_traits;
106
107#[cfg(test)]
108mod ring_test;