Important Builtins in Zig 1.16

Important Builtins in Zig 1.16

This chapter covered the builtins you will see most often as a beginner.

A builtin is a compiler-provided function. Its name starts with @.

@import("std")
@sizeOf(u32)
@alignOf(u32)
@intCast(x)

These are not standard library functions. They are part of the language.

Type and Module Builtins

Use these to import code or work with types.

Builtin	Meaning
@import	Load a Zig module or source file
@TypeOf	Get the type of a value
@typeInfo	Inspect a type
@Type	Build a type from type information
@typeName	Get the name of a type

Example:

const std = @import("std");

const x = 123;
const T = @TypeOf(x);

pub fn main() void {
    std.debug.print("{s}\n", .{@typeName(T)});
}

Memory Layout Builtins

Use these when you need to understand how data is stored.

Builtin	Meaning
@sizeOf	Number of bytes used by a type
@alignOf	Required memory alignment of a type
@offsetOf	Byte offset of a struct field
@bitSizeOf	Number of bits used by a type

Example:

const std = @import("std");

const Point = struct {
    x: i32,
    y: i32,
};

pub fn main() void {
    std.debug.print("size: {}\n", .{@sizeOf(Point)});
    std.debug.print("align: {}\n", .{@alignOf(Point)});
}

Conversion Builtins

Use these when converting values explicitly.

Builtin	Meaning
@intCast	Convert between integer types, checking that the value fits
@truncate	Keep only the low bits of an integer
@floatCast	Convert between floating-point types
@floatFromInt	Convert an integer to a float
@intFromFloat	Convert a float to an integer
@bitCast	Reinterpret bits as another type of the same size

The important distinction is this:

@intCast preserves numeric meaning.
@truncate preserves low bits.
@bitCast preserves raw representation.

Example:

const x: u16 = 300;

const a: u8 = @truncate(x); // 44

Do not use @truncate when you mean “safe integer conversion.” Use @intCast with a range check.

Pointer and Memory Builtins

Use these when working close to raw memory.

Builtin	Meaning
@ptrCast	Reinterpret a pointer as another pointer type
@alignCast	Assert stronger pointer alignment
@constCast	Remove const from a pointer
@volatileCast	Change volatile qualification
@memcpy	Copy memory from source to destination
@memset	Fill memory with a repeated value

Example:

var buffer = [_]u8{0} ** 5;
const text = "hello";

@memcpy(&buffer, text);

Use pointer casts carefully. They do not move memory, fix alignment, or prove that the pointed-to memory has the new type.

Compile-Time Control Builtins

Use these to guide compilation.

Builtin	Meaning
@compileError	Stop compilation with a message
@compileLog	Print compile-time debugging information
@setEvalBranchQuota	Raise the compile-time branch limit
@panic	Stop the running program with a message

Example:

comptime {
    if (@sizeOf(usize) != 8) {
        @compileError("this program requires a 64-bit target");
    }
}

@compileError is for invalid code or unsupported targets.

@panic is for runtime states that should not happen.

File Builtins

Use these to include build-time files.

Builtin	Meaning
@embedFile	Embed a file’s bytes into the executable

Example:

const help_text = @embedFile("help.txt");

The file is read during compilation. The final executable contains the bytes.

Beginner Rule

Most Zig programs use only a small set of builtins often:

@import
@sizeOf
@alignOf
@TypeOf
@intCast
@truncate
@floatCast
@bitCast
@ptrCast
@memcpy
@panic
@compileError
@embedFile

Learn these first.

Do not try to memorize every builtin at once. Read each one by asking:

What special thing is the compiler being asked to do?

That question usually explains the code.