Skip to content

Zig Metaprogramming#

Overview#

Zig's metaprogramming is driven by a few basic concepts:

  • Types are valid values at compile-time
  • most runtime code will also work at compile-time
  • struct field evaluation is compile-time duck-typed
  • the zig standard library gives you tools to perform compile-time reflection
  • examples:

  • multiple dispatch

    Zig
    const std = @import("std");

fn foo(x : anytype) @TypeOf(x) {
    // note that this if statement happens at compile-time, not runtime.
    if (@TypeOf(x) == i64) {
        return x + 2;
    } else {
        return 2 * x;
    }
}

pub fn main() void {
    var x: i64 = 47;
    var y: i32 =  47;

    std.debug.print("i64-foo: {}\n", .{foo(x)});
    std.debug.print("i32-foo: {}\n", .{foo(y)});
}

  • generic Types

    Zig
    fn Vec2Of(comptime T: type) type {
    return struct{
        x: T,
        y: T
    };
}

const V2i64 = Vec2Of(i64);
const V2f64 = Vec2Of(f64);

pub fn main() void {
    var vi = V2i64{.x = 47, .y = 47};
    var vf = V2f64{.x = 47.0, .y = 47.0};

    std.debug.print("i64 vector: {}\n", .{vi});
    std.debug.print("f64 vector: {}\n", .{vf});
}

Compile Time Execution#

  • Blocks of code may be forcibly executed at compile time using the comptime keyword. In this example, the variables x and y are equivalent.
Zig
test "comptime blocks" {
    var x = comptime fibonacci(10);

    var y = comptime blk: {
        break :blk fibonacci(10);
    };
}
  • Integer literals are of the type comptime_int. These are special in that they have no size (they cannot be used at runtime!), and they have arbitrary precision. comptime_int values coerce to any integer type that can hold them. They also coerce to floats. Character literals are of this type.
Zig
test "comptime_int" {
    const a = 12;
    const b = a + 10;

    const c: u4 = a;
    const d: f32 = b;
}

  • comptime_float is also available, which internally is an f128. These cannot be coerced to integers, even if they hold an integer value.

  • function parameters in Zig can be tagged as being comptime, meaning value passed must be known at compile time

Zig
fn Matrix(
    comptime T: type,
    comptime width: comptime_int,
    comptime height: comptime_int,
) type {
    return [height][width]T;
}

test "returning a type" {
    expect(Matrix(f32, 4, 4) == [4][4]f32);
}

Gotchas/Surprises#

  • no peer type resolution in comptime execution
  • all comptime values do not obey usual lifetime rules;
  • have "static" lifetimes (can think of values as garbage collected)
  • anytype struct fields are allowed
  • turns the struct into a comptime type

  • NOTE: allows the type of the field to be mutable

    Zig
    const ArgTuple = struct {
  tuple: anytype = .{},
};
var arg_list = ArgTuple{};
for (args) |arg| {
  if (@TypeOf(arg) == ?u21) {
    if (arg) |cp| {
      arg_list.tuple = arg_list.tuple ++ .{ctUtf8EncodeChar(cp)};
    } else {
      arg_list.tuple = arg_list.tuple ++ .{"null"};
    }
  } else if (@TypeOf(arg) == u21) {
    arg_list.tuple = arg_list.tuple ++ .{ctUtf8EncodeChar(arg)};
  } else {
    arg_list.tuple = arg_list.tuple ++ .{arg};
  }
}

  • can use comptime var to create compile time closures

  • uses anonymous struct literals to avoid compiler caching
  • can be buggy in complex cases
  • Look at zorrow, a simple rust-like borrow checker implemented using this technique

Reflection#

  • Types in Zig are values of the type type, only available at compile time
Zig
test "branching on types" {
    const a = 5;
    const b: if (a < 10) f32 else i32 = 5;
}

  • can reflect upon types using the built-in @typeInfo, which takes in a type and returns a tagged union.

  • tagged union type can be found in std.builtin.TypeInfo (info on how to make use of imports and std later)

Zig
fn addSmallInts(comptime T: type, a: T, b: T) T {
    return switch (@typeInfo(T)) {
        .ComptimeInt => a + b,
        .Int => |info| if (info.bits <= 16)
            a + b
        else
            @compileError("ints too large"),
        else => @compileError("only ints accepted"),
    };
}
test "typeinfo switch" {
    const x = addSmallInts(u16, 20, 30);
    expect(@TypeOf(x) == u16);
    expect(x == 50);
}

  • can use the @Type function to create a type/reify from a @typeInfo. @Type is implemented for most types but is notably unimplemented for enums, unions, functions

  • anonymous struct syntax is used with .{}, because the T in T{} can be inferred. In this example we will get a compile error if the Int tag isn’t set

Zig
fn GetBiggerInt(comptime T: type) type {
    return @Type(.{
        .Int = .{
            .bits = @typeInfo(T).Int.bits + 1,
            .signedness = @typeInfo(T).Int.signedness,
        },
    });
}

test "@Type" {
    expect(GetBiggerInt(u8) == u9);
    expect(GetBiggerInt(i31) == i32);
}

Generic Types#

  • Generic types are specified through explicit parametric type constructor functions

  • Returning a struct type is how you make generic data structures in Zig. The usage of @This is required here, which gets the type of the innermost struct, union, or enum. Here std.mem.eql is also used which compares two slices.

Zig
fn Vec(
    comptime count: comptime_int,
    comptime T: type,
) type {
    return struct {
        data: [count]T,
        const Self = @This();

        fn abs(self: Self) Self {
            var tmp = Self{ .data = undefined };
            for (self.data) |elem, i| {
                tmp.data[i] = if (elem < 0)
                    -elem
                else
                    elem;
            }
            return tmp;
        }

        fn init(data: [count]T) Self {
            return Self{ .data = data };
        }
    };
}

const eql = @import("std").mem.eql;

test "generic vector" {
    const x = Vec(3, f32).init([_]f32{ 10, -10, 5 });
    const y = x.abs();
    expect(eql(f32, &y.data, &[_]f32{ 10, 10, 5 }));
}
  • The types of function parameters can also be inferred by using anytype in place of a type. @TypeOf can then be used on the parameter.
Zig
fn plusOne(x: anytype) @TypeOf(x) {
    return x + 1;
}

test "inferred function parameter" {
    expect(plusOne(@as(u32, 1)) == 2);
}
  • Comptime also introduces the operators ++ and ** for concatenating and repeating arrays and slices. These operators do not work at runtime.
Zig
test "++" {
    const x: [4]u8 = undefined;
    const y = x[0..];

    const a: [6]u8 = undefined;
    const b = a[0..];

    const new = y ++ b;
    expect(new.len == 10);
}

test "**" {
    const pattern = [_]u8{ 0xCC, 0xAA };
    const memory = pattern ** 3;
    expect(eql(
        u8,
        &memory,
        &[_]u8{ 0xCC, 0xAA, 0xCC, 0xAA, 0xCC, 0xAA }
    ));
}

Examples#

Generic Types through Functors#

  • The function returns a type, which means it can only be called at comptime. It defines two structs:

    Zig
    fn LinkedList(comptime T: type) type {
    return struct {
        pub const Node = struct {
            prev: ?*Node = null,
            next: ?*Node = null,
            data: T,
        };

        first: ?*Node = null,
        last: ?*Node = null,
        len: usize = 0,
    };
}

  • main LinkedList struct

  • Node struct, namespaced inside the main struct
  • structs can namespace functions and variables
  • useful for introspection when creating composite types
    Zig
    // To try this code, paste both definitions in the same file.
const PointList = LinkedList(Point);
const p = Point{ .x = 0, .y = 2, .z = 8 };

var my_list = PointList{};

// A complete implementation would offer an `append` method.
// For now let's add the new node manually.
var node = PointList.Node{ .data = p };
my_list.first = &node;
my_list.last = &node;
my_list.len = 1;

Dynamic specialization#

  • type anytype binds to anything
Zig
fn makeCoupleOf(x: anytype) [2]@TypeOf(x) {
    return [2]@TypeOf(x){ x, x };
}
  • allows specialization based on call types
Zig
fn ReturnType(comptime T: type) type {
    comptime var info = @typeInfo(T);
    if (info == .Int) {
        info.Int.bits /= 2;
        return @Type(info);
    } else {
        return T;
    }
}

pub fn sqrt(x: anytype) ReturnType(@TypeOf(x)) {
    const T = @TypeOf(x);
    switch (@typeInfo(T)) {
        .ComptimeFloat, .Float => return @sqrt(x),
        .ComptimeInt => {
            if (x < 0) {
                @compileError("sqrt on negative number");
            }
            return T(sqrtInt(u128, x));
        },
        .Int => return sqrtInt(T, x),
        else => @compileError("not implemented for " ++ @typeName(T)),
    }
}