Zig Reference

Zig's comptime keyword allows any code to execute at compile time using the same language, eliminating the need for separate macro syntax or template metaprogramming. Functions can accept comptime parameters (e.g., comptime T: type) to generate specialized types, effectively implementing generics. For example, fn Matrix(comptime T: type, comptime rows: usize, comptime cols: usize) type returns a struct with a data field of type [rows][cols]T. The @typeInfo builtin enables reflection, and inline for unrolls loops over struct fields at compile time.

defer executes its expression when the enclosing scope exits, regardless of whether the function returns normally or with an error. It is used for deterministic resource cleanup like file.close() or allocator.free(). errdefer only executes when the function returns an error, making it ideal for cleanup that should only happen on failure paths. For example, after allocating a buffer, errdefer allocator.free(buf) ensures the buffer is freed if a subsequent operation fails, but keeps it allocated on success.

Error unions (ErrorSet!PayloadType) encode both success and failure in the return type, making error handling visible in the type system. The try keyword propagates errors upward: const data = try readFile("input.txt") returns the error to the caller if readFile fails. The catch keyword handles errors locally: compute() catch 0 provides a default value, or catch |err| { ... } runs recovery logic. Named error sets (const E = error{NotFound, PermissionDenied}) define domain-specific error types.

Optional types (?T) explicitly encode the possibility of absence in the type system. A ?i32 can hold either an i32 value or null. To access the inner value, you must use if-unwrap: if (x) |val| { use(val); } which only enters the block when x is non-null, with val bound to the unwrapped value. This eliminates null pointer dereferences at compile time because you cannot accidentally use an optional without checking it first.

Zig requires passing allocators explicitly to make all memory allocations visible and controllable. There is no hidden global allocator or implicit heap allocation. This design enables swapping allocators per context: use page_allocator in production, std.testing.allocator in tests (which detects memory leaks), arena allocators for batch allocations, or fixed-buffer allocators for stack-based allocation. It also makes code auditable since every allocation site is explicitly visible in the source.

Tagged unions (union(enum)) combine a union with an enum discriminant, enabling type-safe variant types. Declaring const Value = union(enum) { int: i32, float: f64, none: void } creates a type that can hold exactly one of the variants at a time. Switch expressions on tagged unions are exhaustive, meaning the compiler ensures all variants are handled. This is Zig's approach to sum types, commonly used for representing values that can be one of several different types.

Zig has a first-class test framework built into the language. Test blocks are declared with test "name" { ... } directly in source files alongside the code they test. Assertions use try std.testing.expectEqual(expected, actual) and try std.testing.expect(condition). Running zig test src/main.zig executes all tests, and --test-filter allows running specific tests. The std.testing.allocator detects memory leaks by tracking all allocations and failing the test if any are not freed.

A pointer (*T) references a single value of type T and is dereferenced with ptr.* syntax. A slice ([]T) is a fat pointer containing both a pointer to the start of a contiguous sequence and its length, enabling bounds-checked indexing. Slices are created from arrays using range syntax: arr[1..4] produces a slice of 3 elements. Const slices ([]const T) prevent modification of the underlying data. Slices are Zig's primary abstraction for working with contiguous memory regions safely.