API reference

Every declaration below is extracted from zig-benchmarks's source, with the doc comments as written there. A declaration listed without prose is public but undocumented in the source.

BenchmarkOptions

const BenchmarkOptions = struct

Configuration options for individual benchmarks

BenchmarkResult

const BenchmarkResult = struct

Results from a benchmark run, containing timing samples and statistical analysis

deinit

fn deinit(self: *BenchmarkResult) void

Free the samples ArrayList

toJson

fn toJson(self: *const BenchmarkResult, allocator: Allocator) ![]u8

Export this result as a JSON string (legacy format) Note: Use the export module for more advanced export features

Stats

const Stats = struct

Statistical analysis functions for benchmark samples

mean

fn mean(samples: []const u64) f64

Calculate the arithmetic mean (average) of samples Returns 0.0 for empty samples

stddev

fn stddev(samples: []const u64, mean_val: f64) f64

Calculate the standard deviation using Bessel's correction (n-1) Returns 0.0 for samples with length <= 1

percentile

fn percentile(samples: []u64, p: f64) u64

Calculate a percentile value (p should be between 0.0 and 1.0) Note: This sorts the samples array in-place Examples: p=0.5 for median (P50), p=0.99 for P99

min

fn min(samples: []const u64) u64

Find the minimum value in samples Returns 0 for empty samples

max

fn max(samples: []const u64) u64

Find the maximum value in samples Returns 0 for empty samples

Benchmark

const Benchmark = struct

init

fn init(name: []const u8, func: *const fn () void) Benchmark

withOptions

fn withOptions(name: []const u8, func: *const fn () void, opts: BenchmarkOptions) Benchmark

withAllocator

fn withAllocator(name: []const u8, func: *const fn (Allocator) void) Benchmark

withAllocatorAndOptions

fn withAllocatorAndOptions(name: []const u8, func: *const fn (Allocator) void, opts: BenchmarkOptions) Benchmark

run

fn run(self: *const Benchmark, allocator: Allocator) !BenchmarkResult

BenchmarkSuite

const BenchmarkSuite = struct

A suite of benchmarks to run together Manages multiple benchmarks and provides comparison features

init

fn init(allocator: Allocator) BenchmarkSuite

Initialize a new benchmark suite

deinit

fn deinit(self: *BenchmarkSuite) void

Clean up the suite and free resources

add

fn add(self: *BenchmarkSuite, name: []const u8, func: *const fn () void) !void

Add a simple benchmark function to the suite The function should take no arguments and return void

addWithOptions

fn addWithOptions(self: *BenchmarkSuite, name: []const u8, func: *const fn () void, opts: BenchmarkOptions) !void

Add a benchmark with custom options (warmup, iterations, timing)

addWithAllocator

fn addWithAllocator(self: *BenchmarkSuite, name: []const u8, func: *const fn (Allocator) void) !void

Add a benchmark that requires an allocator parameter Useful for testing allocation-heavy operations

addWithAllocatorAndOptions

fn addWithAllocatorAndOptions(self: *BenchmarkSuite, name: []const u8, func: *const fn (Allocator) void, opts: BenchmarkOptions) !void

Add a benchmark with both custom allocator and options

setFilter

fn setFilter(self: *BenchmarkSuite, filter: []const u8) void

setBaseline

fn setBaseline(self: *BenchmarkSuite, path: []const u8) void

matchesFilter

fn matchesFilter(self: *const BenchmarkSuite, name: []const u8) bool

saveBaseline

fn saveBaseline(self: *BenchmarkSuite, results: []const BenchmarkResult, path: []const u8) !void

run

fn run(self: *BenchmarkSuite) !void

Formatter

const Formatter = struct

Formatter for beautiful CLI output with ANSI colors and formatting

RESET

const RESET = "\x1b[0m"; // Reset all attributes

BOLD

const BOLD = "\x1b[1m"; // Bold text

DIM

const DIM = "\x1b[2m"; // Dimmed text

CYAN

const CYAN = "\x1b[36m"; // Cyan color

GREEN

const GREEN = "\x1b[32m"; // Green color (used for success/fast)

YELLOW

const YELLOW = "\x1b[33m"; // Yellow color (used for warnings/comparisons)

BLUE

const BLUE = "\x1b[34m"; // Blue color (used for info)

MAGENTA

const MAGENTA = "\x1b[35m"; // Magenta color

printHeader

fn printHeader(self: Formatter, file: std.fs.File) !void

Print the benchmark suite header

printBenchmarkStart

fn printBenchmarkStart(self: Formatter, file: std.fs.File, name: []const u8) !void

printResult

fn printResult(self: Formatter, file: std.fs.File, result: *const BenchmarkResult) !void

printSummary

fn printSummary(self: Formatter, file: std.fs.File, results: []const BenchmarkResult) !void

slice

fn slice(self: *const FormattedValue) []const u8

bench

fn bench(name: []const u8, func: *const fn () void) !void

benchWithOptions

fn benchWithOptions(name: []const u8, func: *const fn () void, opts: BenchmarkOptions) !void

AsyncBenchmark

const AsyncBenchmark = struct

init

fn init(name: []const u8, func: *const fn () anyerror!void) AsyncBenchmark

withOptions

fn withOptions(name: []const u8, func: *const fn () anyerror!void, opts: BenchmarkOptions) AsyncBenchmark

run

fn run(self: *const AsyncBenchmark, allocator: Allocator) !BenchmarkResult

AsyncBenchmarkSuite

const AsyncBenchmarkSuite = struct

init

fn init(allocator: Allocator) AsyncBenchmarkSuite

deinit

fn deinit(self: *AsyncBenchmarkSuite) void

add

fn add(self: *AsyncBenchmarkSuite, name: []const u8, func: *const fn () anyerror!void) !void

addWithOptions

fn addWithOptions(self: *AsyncBenchmarkSuite, name: []const u8, func: *const fn () anyerror!void, opts: BenchmarkOptions) !void

setFilter

fn setFilter(self: *AsyncBenchmarkSuite, filter: []const u8) void

setBaseline

fn setBaseline(self: *AsyncBenchmarkSuite, path: []const u8) void

saveBaseline

fn saveBaseline(self: *AsyncBenchmarkSuite, results: []const BenchmarkResult, path: []const u8) !void

run

fn run(self: *AsyncBenchmarkSuite) !void