# Buffers

Fixed-capacity containers implementing the `Buffer<T>` interface. When full, `push` silently evicts the oldest element and returns it. Useful for sliding windows, bounded logs, and streaming aggregates.

## Implementations

### ArrayRingBuffer

Pre-allocated array with head pointer and modular arithmetic. All operations are O(1).

| Operation  | Best | Average | Worst |
| :--------- | :--- | :------ | :---- |
| Space      | O(n) | O(n)    | O(n)  |
| `push`     | O(1) | O(1)    | O(1)  |
| `pop`      | O(1) | O(1)    | O(1)  |
| `shift`    | O(1) | O(1)    | O(1)  |
| `peek`     | O(1) | O(1)    | O(1)  |
| `peekLast` | O(1) | O(1)    | O(1)  |
| `get`      | O(1) | O(1)    | O(1)  |
| Iterate    | O(n) | O(n)    | O(n)  |

**Strengths:** All operations O(1). No reallocation — array is pre-allocated to capacity. Cache-friendly contiguous memory. Both-end removal via `shift` (oldest) and `pop` (newest).

**Weaknesses:** Fixed capacity — cannot grow. Unused slots waste memory if the buffer is mostly empty.

## When to use

| Use case                                           | Recommendation                                                        |
| :------------------------------------------------- | :-------------------------------------------------------------------- |
| Rate-limit sliding window (keep last N timestamps) | **ArrayRingBuffer** — O(1) push + evict, bounded memory               |
| Bounded event/audit log                            | **ArrayRingBuffer** — automatic eviction, iterate oldest-to-newest    |
| Streaming aggregates (moving average, etc.)        | **ArrayRingBuffer** — O(1) access by index for windowed computation   |
| Undo stack with bounded history                    | **ArrayRingBuffer** — `push` to add, `pop` to undo, auto-evict oldest |
| Unbounded growth needed                            | Use a **Queue** instead — buffers are fixed-capacity by design        |

**Default choice: ArrayRingBuffer.** Currently the only implementation. It covers all fixed-capacity ring buffer use cases with optimal complexity.