refraction-types 0.1.1

# Bounded Ring Buffer

A zero-dependency, fixed-capacity ring buffer designed for high-performance networking workloads with predictable memory behavior and an ergonomic byte-oriented API.

## Why This Exists

This crate was created while building networking transport code and a Redis-like data flow layer.
The goal was a simple, fast, dependency-free structure that is tuned for network transmission and
buffered data handling. Existing crates did not give enough control over how data flows through the
buffer, so this crate was split out to reuse across future projects and to become more generally useful
over time.

## Features

- **Zero dependencies**: No external crates required.
- **Predictable memory**: Fixed capacity, no dynamic allocations during operation.
- **Overwrite-on-full semantics**: Automatically drops oldest data when buffer is full.
- **Primary batch API**: `enqueue_slice`/`dequeue_slice` for transport-friendly chunked I/O.
- **Byte-oriented API**: Specialized methods for numeric types (u8–u128, i8–i128, f32, f64, usize, isize) with big-endian encoding.
- **Flexible operations**: Slice-based enqueue/dequeue for batch operations.
- **Comprehensive tests**: 60+ test cases covering wrap-around, overwrite, and edge cases.

## Examples

### enqueue/dequeue

```rust
use refraction_types::ring_buffer::BoundedRingBuffer;

fn main() {
    let mut buffer = BoundedRingBuffer::<u8>::with_capacity(8);

    buffer.enqueue(10);
    buffer.enqueue(20);

    assert_eq!(buffer.dequeue(), Some(10));
    assert_eq!(buffer.dequeue(), Some(20));
    assert_eq!(buffer.dequeue(), None);
}
```

### enqueue_slice/dequeue_slice

```rust
use refraction_types::ring_buffer::BoundedRingBuffer;

fn main() {
    let mut buffer = BoundedRingBuffer::<u8>::with_capacity(8);

    // Main data path: batch enqueue/dequeue.
    buffer.enqueue_slice(&[1, 2, 3, 4]);

    let mut out = [0_u8; 4];
    let read = buffer.dequeue_slice(&mut out, 4);
    assert_eq!(read, 4);
    assert_eq!(out, [1, 2, 3, 4]);
}
```

## Main Data Path: enqueue_slice/dequeue_slice

For transport/protocol workloads, treat `enqueue_slice` and `dequeue_slice` as the primary API:

- `enqueue_slice(&[T])` appends a chunk while preserving order.
- `dequeue_slice(&mut [T], n)` drains up to `n` elements into a caller-provided buffer.
- If input chunk is larger than capacity, only the newest tail that fits is kept.
- If output request is larger than current length, the call returns only what is available.

Single-element `enqueue`/`dequeue` are still useful for control logic and tests, but batch calls are the
fast path for streaming data.

## Semantics

- **front()**: Returns reference to the oldest (next to be dequeued) element.
- **back()**: Returns reference to the newest (most recently enqueued) element.
- **peek_*()**: Non-consuming read of a typed value from the front.
- **dequeue_*()**: Consuming read; advances the read pointer.
- **enqueue()**: Adds a single element; overwrites oldest if full.
- **enqueue_slice()/dequeue_slice()**: Preferred bulk API for steady-state data transfer.
- **advance(size)**: Simulates writing `size` bytes as if they were enqueued.

## Byte-Oriented Specializations

The buffer provides typed methods for common network data types, all using big-endian encoding:

```rust
let mut buf = BoundedRingBuffer::<u8>::with_capacity(100);

buf.enqueue_u16(0xCAFE);
buf.enqueue_i32(-12345);
buf.enqueue_f64(3.14);

assert_eq!(buf.peek_u16(), Some(0xCAFE));
assert_eq!(buf.dequeue_i32(), Some(-12345));
```

## Current Limitations & Roadmap

- [ ] Thread-safe variants (SPSC, MPSC)
- [ ] Custom allocators
- [ ] No-std support
- [ ] Zero-copy slice views
- [ ] Benchmarks vs. std collections

## License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.