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.