# `StatifierUI.Trace.Buffer`
[🔗](https://github.com/riddler/statifier-ui/blob/v0.11.0/lib/statifier_ui/trace/buffer.ex#L1)

A fixed-capacity, drop-oldest store of `%StatifierUI.Trace.Message{}`
values - the memory-safety mechanism a chatty session needs so a notebook
does not grow without bound (decision 8 of the plan).

Backed by `:queue` rather than a list: `push/2` at capacity has to drop
from the far end, and a list would make that `O(n)` on every message once
full. `size/1` is tracked on the struct rather than derived, because
`:queue.len/1` is itself `O(n)`.

There is no drop notification. Every message carries a per-session
monotonic `seq` starting at `0`, so a consumer detects loss by reading the
first buffered message's `seq` directly - a synthetic drop message would
itself consume a `seq` and corrupt the very counter it would be reporting
on. `dropped/1` exists for a status line, not to replace that.

# `t`

```elixir
@type t() :: %StatifierUI.Trace.Buffer{
  capacity: pos_integer(),
  dropped: non_neg_integer(),
  entries: :queue.queue(StatifierUI.Trace.Message.t()),
  size: non_neg_integer()
}
```

# `clear`

```elixir
@spec clear(t()) :: t()
```

Empties `buffer`, preserving `capacity` and resetting `dropped` to `0`.

# `dropped`

```elixir
@spec dropped(t()) :: non_neg_integer()
```

Returns the number of messages lost to capacity since the buffer was created or last cleared.

# `new`

```elixir
@spec new(capacity :: pos_integer()) :: t()
```

Builds an empty buffer holding at most `capacity` messages.

`capacity` is a programmer argument, not an input value derived from
external data, so a non-positive capacity raises `ArgumentError` rather
than returning an error tuple.

# `push`

```elixir
@spec push(t(), StatifierUI.Trace.Message.t()) :: t()
```

Appends `message`, dropping the oldest entry when `buffer` is already at
capacity.

# `size`

```elixir
@spec size(t()) :: non_neg_integer()
```

Returns the number of messages currently held.

# `to_list`

```elixir
@spec to_list(t()) :: [StatifierUI.Trace.Message.t()]
```

Returns `buffer`'s messages oldest-first.

---

*Consult [api-reference.md](api-reference.md) for complete listing*