comptime

Zig places importance on the concept of whether an expression is known at compile-time. There are a few different places this concept is used, and these building blocks are used to keep the language small, readable, and powerful.

Introducing the Compile-Time Concept

Compile-Time Parameters

Compile-time parameters is how Zig implements generics. It is compile-time duck typing.

fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}
fn gimmeTheBiggerFloat(a: f32, b: f32) f32 {
    return max(f32, a, b);
}
fn gimmeTheBiggerInteger(a: u64, b: u64) u64 {
    return max(u64, a, b);
}

In Zig, types are first-class citizens. They can be assigned to variables, passed as parameters to functions, and returned from functions. However, they can only be used in expressions which are known at compile-time, which is why the parameter T in the above snippet must be marked with comptime.

A comptime parameter means that:

• At the callsite, the value must be known at compile-time, or it is a compile error.
• In the function definition, the value is known at compile-time.

For example, if we were to introduce another function to the above snippet:

test.zig

fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}
test "try to pass a runtime type" {
    foo(false);
}
fn foo(condition: bool) void {
    const result = max(
        if (condition) f32 else u64,
        1234,
        5678);
}

$ zig test test.zig
./docgen_tmp/test.zig:9:9: error: values of type 'type' must be comptime known
        if (condition) f32 else u64,
        ^

This is an error because the programmer attempted to pass a value only known at run-time to a function which expects a value known at compile-time.

Another way to get an error is if we pass a type that violates the type checker when the function is analyzed. This is what it means to have compile-time duck typing.

For example:

test.zig

fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}
test "try to compare bools" {
    _ = max(bool, true, false);
}

$ zig test test.zig
./docgen_tmp/test.zig:2:18: error: operator not allowed for type 'bool'
    return if (a > b) a else b;
                 ^
./docgen_tmp/test.zig:5:12: note: called from here
    _ = max(bool, true, false);
           ^
./docgen_tmp/test.zig:4:29: note: called from here
test "try to compare bools" {
                            ^

On the flip side, inside the function definition with the comptime parameter, the value is known at compile-time. This means that we actually could make this work for the bool type if we wanted to:

test.zig

fn max(comptime T: type, a: T, b: T) T {
    if (T == bool) {
        return a or b;
    } else if (a > b) {
        return a;
    } else {
        return b;
    }
}
test "try to compare bools" {
    @import("std").debug.assert(max(bool, false, true) == true);
}

$ zig test test.zig
1/1 test "try to compare bools"...OK
All 1 tests passed.

This works because Zig implicitly inlines if expressions when the condition is known at compile-time, and the compiler guarantees that it will skip analysis of the branch not taken.

This means that the actual function generated for max in this situation looks like this:

fn max(a: bool, b: bool) bool {
    return a or b;
}

All the code that dealt with compile-time known values is eliminated and we are left with only the necessary run-time code to accomplish the task.

This works the same way for switch expressions - they are implicitly inlined when the target expression is compile-time known.

Compile-Time Variables

In Zig, the programmer can label variables as comptime. This guarantees to the compiler that every load and store of the variable is performed at compile-time. Any violation of this results in a compile error.

This combined with the fact that we can inline loops allows us to write a function which is partially evaluated at compile-time and partially at run-time.

For example:

comptime_vars.zig

const assert = @import("std").debug.assert;
const CmdFn = struct {
    name: []const u8,
    func: fn(i32) i32,
};
const cmd_fns = [_]CmdFn{
    CmdFn {.name = "one", .func = one},
    CmdFn {.name = "two", .func = two},
    CmdFn {.name = "three", .func = three},
};
fn one(value: i32) i32 { return value + 1; }
fn two(value: i32) i32 { return value + 2; }
fn three(value: i32) i32 { return value + 3; }
fn performFn(comptime prefix_char: u8, start_value: i32) i32 {
    var result: i32 = start_value;
    comptime var i = 0;
    inline while (i < cmd_fns.len) : (i += 1) {
        if (cmd_fns[i].name[0] == prefix_char) {
            result = cmd_fns[i].func(result);
        }
    }
    return result;
}
test "perform fn" {
    assert(performFn('t', 1) == 6);
    assert(performFn('o', 0) == 1);
    assert(performFn('w', 99) == 99);
}

$ zig test comptime_vars.zig
1/1 test "perform fn"...OK
All 1 tests passed.

This example is a bit contrived, because the compile-time evaluation component is unnecessary; this code would work fine if it was all done at run-time. But it does end up generating different code. In this example, the function performFn is generated three different times, for the different values of prefix_char provided:

// From the line:
// assert(performFn('t', 1) == 6);
fn performFn(start_value: i32) i32 {
    var result: i32 = start_value;
    result = two(result);
    result = three(result);
    return result;
}

// From the line:
// assert(performFn('o', 0) == 1);
fn performFn(start_value: i32) i32 {
    var result: i32 = start_value;
    result = one(result);
    return result;
}

// From the line:
// assert(performFn('w', 99) == 99);
fn performFn(start_value: i32) i32 {
    var result: i32 = start_value;
    return result;
}

Note that this happens even in a debug build; in a release build these generated functions still pass through rigorous LLVM optimizations. The important thing to note, however, is not that this is a way to write more optimized code, but that it is a way to make sure that what should happen at compile-time, does happen at compile-time. This catches more errors and as demonstrated later in this article, allows expressiveness that in other languages requires using macros, generated code, or a preprocessor to accomplish.

Compile-Time Expressions

In Zig, it matters whether a given expression is known at compile-time or run-time. A programmer can use a comptime expression to guarantee that the expression will be evaluated at compile-time. If this cannot be accomplished, the compiler will emit an error. For example:

test.zig

extern fn exit() noreturn;
test "foo" {
    comptime {
        exit();
    }
}

$ zig test test.zig
./docgen_tmp/test.zig:5:9: error: unable to evaluate constant expression
        exit();
        ^
./docgen_tmp/test.zig:5:13: note: referenced here
        exit();
            ^

It doesn't make sense that a program could call exit() (or any other external function) at compile-time, so this is a compile error. However, a comptime expression does much more than sometimes cause a compile error.

Within a comptime expression:

• All variables are comptime variables.
• All if, while, for, and switch expressions are evaluated at compile-time, or emit a compile error if this is not possible.
• All function calls cause the compiler to interpret the function at compile-time, emitting a compile error if the function tries to do something that has global run-time side effects.

This means that a programmer can create a function which is called both at compile-time and run-time, with no modification to the function required.

Let's look at an example:

test.zig

const assert = @import("std").debug.assert;
fn fibonacci(index: u32) u32 {
    if (index < 2) return index;
    return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
    // test fibonacci at run-time
    assert(fibonacci(7) == 13);
    // test fibonacci at compile-time
    comptime {
        assert(fibonacci(7) == 13);
    }
}

$ zig test test.zig
1/1 test "fibonacci"...OK
All 1 tests passed.

Imagine if we had forgotten the base case of the recursive function and tried to run the tests:

test.zig

const assert = @import("std").debug.assert;
fn fibonacci(index: u32) u32 {
    //if (index < 2) return index;
    return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
    comptime {
        assert(fibonacci(7) == 13);
    }
}

$ zig test test.zig
./docgen_tmp/test.zig:5:28: error: operation caused overflow
    return fibonacci(index - 1) + fibonacci(index - 2);
                           ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:10:25: note: called from here
        assert(fibonacci(7) == 13);
                        ^
./docgen_tmp/test.zig:8:18: note: called from here
test "fibonacci" {
                 ^
./docgen_tmp/test.zig:5:21: note: referenced here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:10:25: note: referenced here
        assert(fibonacci(7) == 13);
                        ^

The compiler produces an error which is a stack trace from trying to evaluate the function at compile-time.

Luckily, we used an unsigned integer, and so when we tried to subtract 1 from 0, it triggered undefined behavior, which is always a compile error if the compiler knows it happened. But what would have happened if we used a signed integer?

test.zig

const assert = @import("std").debug.assert;
fn fibonacci(index: i32) i32 {
    //if (index < 2) return index;
    return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
    comptime {
        assert(fibonacci(7) == 13);
    }
}

$ zig test test.zig
./docgen_tmp/test.zig:5:21: error: evaluation exceeded 1000 backwards branches
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:5:21: note: called from here
    return fibonacci(index - 1) + fibonacci(index - 2);
                    ^
./docgen_tmp/test.zig:10:25: note: referenced here
        assert(fibonacci(7) == 13);
                        ^

The compiler noticed that evaluating this function at compile-time took a long time, and thus emitted a compile error and gave up. If the programmer wants to increase the budget for compile-time computation, they can use a built-in function called @setEvalBranchQuota to change the default number 1000 to something else.

What if we fix the base case, but put the wrong value in the assert line?

test.zig

const assert = @import("std").debug.assert;
fn fibonacci(index: i32) i32 {
    if (index < 2) return index;
    return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
    comptime {
        assert(fibonacci(7) == 99999);
    }
}

$ zig test test.zig
./lib/std/debug.zig:228:14: error: unable to evaluate constant expression
    if (!ok) unreachable; // assertion failure
             ^
./docgen_tmp/test.zig:10:15: note: called from here
        assert(fibonacci(7) == 99999);
              ^
./docgen_tmp/test.zig:8:18: note: called from here
test "fibonacci" {
                 ^
./docgen_tmp/test.zig:10:15: note: referenced here
        assert(fibonacci(7) == 99999);
              ^

What happened is Zig started interpreting the assert function with the parameter ok set to false. When the interpreter hit unreachable it emitted a compile error, because reaching unreachable code is undefined behavior, and undefined behavior causes a compile error if it is detected at compile-time.

In the global scope (outside of any function), all expressions are implicitly comptime expressions. This means that we can use functions to initialize complex static data. For example:

test.zig

const first_25_primes = firstNPrimes(25);
const sum_of_first_25_primes = sum(&first_25_primes);
fn firstNPrimes(comptime n: usize) [n]i32 {
    var prime_list: [n]i32 = undefined;
    var next_index: usize = 0;
    var test_number: i32 = 2;
    while (next_index < prime_list.len) : (test_number += 1) {
        var test_prime_index: usize = 0;
        var is_prime = true;
        while (test_prime_index < next_index) : (test_prime_index += 1) {
            if (test_number % prime_list[test_prime_index] == 0) {
                is_prime = false;
                break;
            }
        }
        if (is_prime) {
            prime_list[next_index] = test_number;
            next_index += 1;
        }
    }
    return prime_list;
}
fn sum(numbers: []const i32) i32 {
    var result: i32 = 0;
    for (numbers) |x| {
        result += x;
    }
    return result;
}
test "variable values" {
    @import("std").debug.assert(sum_of_first_25_primes == 1060);
}

$ zig test test.zig
1/1 test "variable values"...OK
All 1 tests passed.

When we compile this program, Zig generates the constants with the answer pre-computed. Here are the lines from the generated LLVM IR:

@0 = internal unnamed_addr constant [25 x i32] [i32 2, i32 3, i32 5, i32 7, i32 11, i32 13, i32 17, i32 19, i32 23, i32 29, i32 31, i32 37, i32 41, i32 43, i32 47, i32 53, i32 59, i32 61, i32 67, i32 71, i32 73, i32 79, i32 83, i32 89, i32 97]
@1 = internal unnamed_addr constant i32 1060

Note that we did not have to do anything special with the syntax of these functions. For example, we could call the sum function as is with a slice of numbers whose length and values were only known at run-time.

Generic Data Structures

Zig uses these capabilities to implement generic data structures without introducing any special-case syntax. If you followed along so far, you may already know how to create a generic data structure.

Here is an example of a generic List data structure, that we will instantiate with the type i32. In Zig we refer to the type as List(i32).

fn List(comptime T: type) type {
    return struct {
        items: []T,
        len: usize,
    };
}

That's it. It's a function that returns an anonymous struct. For the purposes of error messages and debugging, Zig infers the name "List(i32)" from the function name and parameters invoked when creating the anonymous struct.

To keep the language small and uniform, all aggregate types in Zig are anonymous. To give a type a name, we assign it to a constant:

const Node = struct {
    next: *Node,
    name: []u8,
};

This works because all top level declarations are order-independent, and as long as there isn't an actual infinite regression, values can refer to themselves, directly or indirectly. In this case, Node refers to itself as a pointer, which is not actually an infinite regression, so it works fine.

Case Study: printf in Zig

Putting all of this together, let's see how printf works in Zig.

printf.zig

const warn = @import("std").debug.warn;
const a_number: i32 = 1234;
const a_string = "foobar";
pub fn main() void {
    warn("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
}

$ zig build-exe printf.zig
$ ./printf
here is a string: 'foobar' here is a number: 1234

Let's crack open the implementation of this and see how it works:

/// Calls print and then flushes the buffer.
pub fn printf(self: *OutStream, comptime format: []const u8, args: var) anyerror!void {
    const State = enum {
        Start,
        OpenBrace,
        CloseBrace,
    };
    comptime var start_index: usize = 0;
    comptime var state = State.Start;
    comptime var next_arg: usize = 0;
    inline for (format) |c, i| {
        switch (state) {
            State.Start => switch (c) {
                '{' => {
                    if (start_index < i) try self.write(format[start_index..i]);
                    state = State.OpenBrace;
                },
                '}' => {
                    if (start_index < i) try self.write(format[start_index..i]);
                    state = State.CloseBrace;
                },
                else => {},
            },
            State.OpenBrace => switch (c) {
                '{' => {
                    state = State.Start;
                    start_index = i;
                },
                '}' => {
                    try self.printValue(args[next_arg]);
                    next_arg += 1;
                    state = State.Start;
                    start_index = i + 1;
                },
                else => @compileError("Unknown format character: " ++ c),
            },
            State.CloseBrace => switch (c) {
                '}' => {
                    state = State.Start;
                    start_index = i;
                },
                else => @compileError("Single '}' encountered in format string"),
            },
        }
    }
    comptime {
        if (args.len != next_arg) {
            @compileError("Unused arguments");
        }
        if (state != State.Start) {
            @compileError("Incomplete format string: " ++ format);
        }
    }
    if (start_index < format.len) {
        try self.write(format[start_index..format.len]);
    }
    try self.flush();
}

This is a proof of concept implementation; the actual function in the standard library has more formatting capabilities.

Note that this is not hard-coded into the Zig compiler; this is userland code in the standard library.

When this function is analyzed from our example code above, Zig partially evaluates the function and emits a function that actually looks like this:

pub fn printf(self: *OutStream, arg0: i32, arg1: []const u8) !void {
    try self.write("here is a string: '");
    try self.printValue(arg0);
    try self.write("' here is a number: ");
    try self.printValue(arg1);
    try self.write("\n");
    try self.flush();
}

printValue is a function that takes a parameter of any type, and does different things depending on the type:

pub fn printValue(self: *OutStream, value: var) !void {
    switch (@typeInfo(@TypeOf(value))) {
        .Int => {
            return self.printInt(T, value);
        },
        .Float => {
            return self.printFloat(T, value);
        },
        else => {
            @compileError("Unable to print type '" ++ @typeName(T) ++ "'");
        },
    }
}

And now, what happens if we give too many arguments to printf?

test.zig

const warn = @import("std").debug.warn;
const a_number: i32 = 1234;
const a_string = "foobar";
test "printf too many arguments" {
    warn("here is a string: '{}' here is a number: {}\n", .{
        a_string,
        a_number,
        a_number,
    });
}

$ zig test test.zig
./lib/std/fmt.zig:302:13: error: Unused arguments
            @compileError("Unused arguments");
            ^
./lib/std/io/out_stream.zig:28:34: note: called from here
            return std.fmt.format(self, format, args);
                                 ^
./lib/std/debug.zig:65:25: note: called from here
    noasync stderr.print(fmt, args) catch return;
                        ^
./docgen_tmp/test.zig:7:9: note: called from here
    warn("here is a string: '{}' here is a number: {}\n", .{
        ^
./docgen_tmp/test.zig:6:34: note: called from here
test "printf too many arguments" {
                                 ^
./lib/std/io/out_stream.zig:28:34: error: expected type 'std.os.WriteError!void', found '@TypeOf(std.fmt.format).ReturnType.ErrorSet!void'
            return std.fmt.format(self, format, args);
                                 ^
./lib/std/debug.zig:65:25: note: called from here
    noasync stderr.print(fmt, args) catch return;
                        ^
./docgen_tmp/test.zig:7:9: note: called from here
    warn("here is a string: '{}' here is a number: {}\n", .{
        ^
./docgen_tmp/test.zig:6:34: note: called from here
test "printf too many arguments" {
                                 ^
./lib/std/io/out_stream.zig:28:34: note: error set '@TypeOf(std.fmt.format).ReturnType.ErrorSet' cannot cast into error set 'std.os.WriteError'
            return std.fmt.format(self, format, args);
                                 ^

Zig gives programmers the tools needed to protect themselves against their own mistakes.

Zig doesn't care whether the format argument is a string literal, only that it is a compile-time known value that can be coerced to a []const u8:

printf.zig

const warn = @import("std").debug.warn;
const a_number: i32 = 1234;
const a_string = "foobar";
const fmt = "here is a string: '{}' here is a number: {}\n";
pub fn main() void {
    warn(fmt, .{a_string, a_number});
}

$ zig build-exe printf.zig
$ ./printf
here is a string: 'foobar' here is a number: 1234

This works fine.

Zig does not special case string formatting in the compiler and instead exposes enough power to accomplish this task in userland. It does so without introducing another language on top of Zig, such as a macro language or a preprocessor language. It's Zig all the way down.

See also:

• inline while
• inline for