Zig comptime: Turning Array Lengths into Compile-Time Constants

You hardcode 4 beside a four-element array. Weeks later, someone appends a fifth value. The code still compiles, but an off-by-one bug is now waiting in production. Zig’s comptime feature lets you derive that number during compilation, so the binary either matches the data or the build fails.

The useful takeaway: treating array length as an explicit compile-time constant removes a class of synchronization bugs. The price is longer builds and stricter rules about what your build-time code may do. The examples below assume Zig 0.12 or newer.

The brittle magic number

In many languages, array length is a runtime property. You call len() or read .length when you need it. That works, but it hides two problems. First, if you manually duplicate the length into a constant, the copy drifts. Second, if the length feeds into another type—say, a fixed-size buffer or a bitmask—the compiler cannot verify the relationship until runtime, if ever.

Zig already knows the length of a fixed-size array at compile time. my_array.len is a compile-time-known value. The issue is intent and verification. When you write generic code or build-time configuration, making that evaluation explicit with comptime documents the invariant and lets you attach assertions that fail the build.

What comptime actually does

comptime is a keyword that forces a block or expression to be evaluated while the compiler runs. The result is embedded in the binary as a constant. Because Zig represents errors as values through its error-union model, a comptime expression that fails stops compilation with a diagnostic rather than producing a broken binary.

This is not a macro system and not a separate language. It is the same Zig code, executed earlier. The constraint is that comptime code must be side-effect free: no file I/O, no network, no mutable global state. The compiler enforces this, but keeping expressions shallow makes diagnostics easier to read.

A worked example: compile-time table sizing

Suppose you maintain a static lookup table and need its length for a runtime loop. Instead of trusting a magic number, derive it explicitly and guard the invariant.

const std = @import("std");

const sensor_readings = [_]f64{
    22.5,
    23.1,
    21.8,
    24.0,
    23.5,
};

// Evaluate the length during compilation.
const reading_count = comptime sensor_readings.len;

// A compile-time assertion: reject empty tables early.
comptime {
    if (reading_count == 0) {
        @compileError("sensor_readings must contain at least one entry");
    }
}

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();
    var total: f64 = 0.0;
    var i: usize = 0;
    while (i < reading_count) : (i += 1) {
        total += sensor_readings[i];
    }
    const average = total / @as(f64, @floatFromInt(reading_count));
    try stdout.print("Average: {d:.2}\n", .{average});
}

Here, reading_count is not a variable. It is a constant baked into the binary. The while loop uses it as an immediate bound, and the division converts it to f64 at compile time. If someone empties sensor_readings, the @compileError fires and the build stops.

The trade-offs you accept

Comptime is powerful, but it is not free.

Concern	Impact	Mitigation
Compile time	Complex comptime blocks slow the build.	Keep comptime logic small; move heavy computation into a dedicated build step.
Debuggability	Errors point to comptime blocks, not runtime lines.	Use descriptive @compileError messages.
Side effects	Comptime code must be pure; the compiler rejects I/O and mutable state.	Treat comptime as evaluation only.
Version stability	Pre-0.12 Zig lacked stable comptime APIs.	Pin your Zig version; test upgrades in CI.

The most common mistake is attempting runtime work inside a comptime block. Zig will reject it, but the error messages can be opaque if the expression is deeply nested. Keep comptime expressions shallow and purposeful.

Verifying the result

To confirm the example works on your machine, run these commands from the directory containing main.zig. No special permissions are required.

1. Build: zig build-exe main.zig. Expected check: compilation succeeds with no comptime errors or warnings.
2. Run: ./main on Linux/macOS, or main.exe on Windows. Expected check: the program prints the computed average and exits cleanly.
3. Inspect (optional): objdump -d main if binutils is installed. Confirm the loop bound appears as an immediate constant or that the loop is unrolled, rather than loading a length from memory. Risk: disassembly differs by platform and optimization level.

Where to start

Audit your code for hardcoded lengths or .len calls inside performance-sensitive loops. Replace them with explicit comptime constants and add @compileError guards for invariants such as “table size matches enum count.” If build times climb, extract the comptime logic into a separate function so the compiler can cache and reuse the result. The goal is not to use comptime everywhere, but to make the compiler prove the relationships you currently check by hand.