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