# `SnakeBridge.Benchmark`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.16.0/lib/snakebridge/benchmark.ex#L1)

Benchmark utilities for SnakeBridge performance measurement.

Provides functions for measuring execution time, collecting statistics,
and comparing performance across different configurations.

## Usage

    # Single measurement
    result = Benchmark.measure("my_operation", fn -> do_work() end)

    # Multiple iterations with statistics
    stats = Benchmark.run_iterations("my_operation", fn -> do_work() end, 10)

    # Compare two runs
    comparison = Benchmark.compare(baseline_stats, current_stats)

# `comparison`

```elixir
@type comparison() :: %{
  speedup: float(),
  improvement_percent: float(),
  baseline_mean_us: float(),
  current_mean_us: float()
}
```

# `measurement`

```elixir
@type measurement() :: %{
  name: String.t(),
  time_us: non_neg_integer(),
  value: term(),
  error: String.t() | nil
}
```

# `stats`

```elixir
@type stats() :: %{
  name: String.t(),
  iterations: non_neg_integer(),
  mean_us: float(),
  median_us: float(),
  min_us: non_neg_integer(),
  max_us: non_neg_integer(),
  std_dev_us: float(),
  times_us: [non_neg_integer()]
}
```

# `compare`

```elixir
@spec compare(map(), map()) :: comparison()
```

Compares two benchmark results and calculates improvement metrics.

Returns:
- `speedup` - Ratio (> 1.0 means faster)
- `improvement_percent` - Percentage improvement (positive is faster)

# `format_bytes`

```elixir
@spec format_bytes(number()) :: String.t()
```

Formats a byte count to a human-readable string.

## Examples

    iex> Benchmark.format_bytes(1024)
    "1.00 KB"

    iex> Benchmark.format_bytes(1_048_576)
    "1.00 MB"

# `format_time`

```elixir
@spec format_time(number()) :: String.t()
```

Formats a time in microseconds to a human-readable string.

## Examples

    iex> Benchmark.format_time(500)
    "500 µs"

    iex> Benchmark.format_time(5_000)
    "5.00 ms"

    iex> Benchmark.format_time(5_000_000)
    "5.00 s"

# `measure`

```elixir
@spec measure(String.t(), (-> term())) :: measurement()
```

Measures the execution time of a single function call.

Returns a map with:
- `name` - The benchmark name
- `time_us` - Execution time in microseconds
- `value` - The function's return value
- `error` - Error message if the function raised

# `print_comparison`

```elixir
@spec print_comparison(comparison()) :: :ok
```

Prints a comparison between two benchmark runs.

# `print_stats`

```elixir
@spec print_stats(stats()) :: :ok
```

Prints a summary of benchmark statistics.

# `run_iterations`

```elixir
@spec run_iterations(String.t(), (-> term()), non_neg_integer()) :: stats()
```

Runs a function multiple times and collects statistics.

Returns a map with statistical measures:
- `mean_us` - Average time in microseconds
- `median_us` - Median time in microseconds
- `min_us` - Minimum time
- `max_us` - Maximum time
- `std_dev_us` - Standard deviation

---

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