Skip to content

stdlib.bench

Timing and throughput harnesses for micro- and macro-benchmarks.

Generated from v0.65.7. 1 source files, 17 documented symbols.

bench.xi

type BenchResult

Timing result of one benchmark run.

Field Type
name Str
iterations Int
total_ns Int
mean_ns Int
min_ns Int
max_ns Int
stddev_ns Int

Derives: Clone

fn run_bench(name: Str, f: fn() -> Unit) -> BenchResult

Time f once and return the result.

  • Precondition: name.len() > 0
  • Postcondition: result.iterations == 1
  • Postcondition: result.name == name
  • Postcondition: result.total_ns == result.mean_ns
  • Postcondition: result.stddev_ns == 0

fn run_bench_n(name: Str, iterations: Int, f: fn() -> Unit) -> BenchResult

Time f over iterations runs; returns aggregate stats.

  • Precondition: name.len() > 0
  • Precondition: iterations >= 0
  • Postcondition: result.iterations == iterations
  • Postcondition: result.name == name
  • Postcondition: (iterations <= 0) => (result.total_ns == 0 && result.mean_ns == 0 && result.min_ns == 0 && result.max_ns == 0 && result.stddev_ns == 0)

fn compare(a: BenchResult, b: BenchResult) -> Str

Human-readable comparison of two benchmark results.

  • Postcondition: result.len() > 0
  • Postcondition: result.len() >= a.name.len()

fn black_box[T](value: T) -> T

Opaque identity that prevents the optimizer from eliding the value.

  • Postcondition: result == value

fn bench_ops_per_sec_ns(result: &BenchResult) -> Int

Returns operations per second based on mean_ns. Returns 0 if mean_ns is 0 to avoid division by zero. Complexity: O(1). Pure.

  • Postcondition: (result.mean_ns <= 0) => (result == 0)

fn bench_faster_percent(baseline: &BenchResult, candidate: &BenchResult) -> Int

Returns how many percent candidate is faster than baseline. Positive means candidate is faster. Formula: (base - cand) * 100 / base. Returns 0 if baseline.mean_ns is 0. Complexity: O(1). Pure.

  • Postcondition: (baseline.mean_ns <= 0) => (result == 0)

fn bench_min_ns(results: Vec[BenchResult]) -> Int

Returns the minimum mean_ns across all benchmark results. Returns 0 if the vector is empty. Complexity: O(n).

  • Postcondition: (results.len() == 0) => (result == 0)

fn bench_max_ns(results: Vec[BenchResult]) -> Int

Returns the maximum mean_ns across all benchmark results. Returns 0 if the vector is empty. Complexity: O(n).

  • Postcondition: (results.len() == 0) => (result == 0)

fn bench_total_ns(results: Vec[BenchResult]) -> Int

Returns the sum of total_ns across all benchmark results. Complexity: O(n).

  • Postcondition: (results.len() == 0) => (result == 0)

fn bench_median_ns(results: Vec[BenchResult]) -> Int

Returns the median mean_ns across results (middle element by position, unsorted). Complexity: O(1) index access.

  • Postcondition: (results.len() == 0) => (result == 0)

fn bench_human_ns(ns: Int) -> Str

Converts nanoseconds to a human-readable string ("1.23ms", "45us", "100ns"). Complexity: O(1).

  • Postcondition: (ns == 1500000000) => (result == "1.5s")
  • Postcondition: (ns == 1500000) => (result == "1.5ms")
  • Postcondition: (ns == 1500) => (result == "1.5us")
  • Postcondition: (ns == 999) => (result == "999ns")

fn bench_black_box_int(n: Int) -> Int

Wraps black_box for Int values, preventing compiler optimisations from eliminating benchmarked computations. Complexity: O(1). Pure.

  • Postcondition: result == n

fn bench_run_avg(name: Str, iterations: Int, f: fn() -> Unit) -> BenchResult

Runs a benchmark with the given name and iteration count. Alias for run_bench_n. Complexity: runs f exactly iterations times.

  • Postcondition: result.iterations == iterations
  • Postcondition: result.name == name

fn bench_time_fn(f: fn() -> Unit) -> Int

Times a single invocation of f and returns the elapsed nanoseconds. Complexity: runs f exactly once. Defect fix 2026-10-08 (wave 91): used to call run_bench("", f), which violated run_bench's own requires: name.len() > 0 at runtime.

  • Postcondition: result >= 0

fn bench_report(results: Vec[BenchResult]) -> Str

Generates a table report with columns: name, mean, min, max, ops/s. Complexity: O(n).

  • Postcondition: (results.len() == 0) => (result.len() == 124)

fn bench_report_simple(results: Vec[BenchResult]) -> Str

Generates a compact one-line-per-result report. Complexity: O(n).

  • Postcondition: (results.len() == 0) => (result == "")