Optionals and Unions

Zig's optional types and tagged unions make null safety and variant data explicit in the type system. This prevents null pointer errors and makes your code self-documenting.

Optional Types

An optional ?T can hold either a value of type T or null.

const std = @import("std");

fn findIndex(haystack: []const u8, needle: u8) ?usize {
    for (haystack, 0..) |c, i| {
        if (c == needle) return i;
    }
    return null;
}

pub fn main() !void {
    const text = "Hello, World!";

    // Check with if
    if (findIndex(text, 'W')) |index| {
        std.debug.print("Found 'W' at index {}\n", .{index});
    } else {
        std.debug.print("'W' not found\n", .{});
    }

    if (findIndex(text, 'Z')) |index| {
        std.debug.print("Found 'Z' at index {}\n", .{index});
    } else {
        std.debug.print("'Z' not found\n", .{});
    }

    // orelse — provide a default value
    const idx = findIndex(text, 'x') orelse 999;
    std.debug.print("Index with default: {}\n", .{idx});

    // .? — unwrap (crashes if null, use carefully)
    const known_idx = findIndex(text, 'H').?;
    std.debug.print("Known index of 'H': {}\n", .{known_idx});
}

Optional Chaining

Combine optionals with control flow for safe data access.

const std = @import("std");

const User = struct {
    name: []const u8,
    email: ?[]const u8,
    age: ?u32,
};

fn getUserEmail(user: ?User) ?[]const u8 {
    const u = user orelse return null;
    return u.email;
}

fn formatUser(user: User) void {
    std.debug.print("Name: {s}\n", .{user.name});

    if (user.email) |email| {
        std.debug.print("Email: {s}\n", .{email});
    } else {
        std.debug.print("Email: (not provided)\n", .{});
    }

    if (user.age) |age| {
        std.debug.print("Age: {}\n", .{age});
    } else {
        std.debug.print("Age: (not provided)\n", .{});
    }
}

pub fn main() !void {
    const alice = User{ .name = "Alice", .email = "alice@example.com", .age = 30 };
    const bob = User{ .name = "Bob", .email = null, .age = null };

    formatUser(alice);
    std.debug.print("\n", .{});
    formatUser(bob);

    std.debug.print("\nAlice's email: {s}\n", .{getUserEmail(alice) orelse "unknown"});
    std.debug.print("Bob's email: {s}\n", .{getUserEmail(bob) orelse "unknown"});
}

Tagged Unions

Tagged unions hold one of several types, with the active type tracked at runtime.

const std = @import("std");

const Value = union(enum) {
    integer: i64,
    float: f64,
    boolean: bool,
    string: []const u8,
    nothing,

    fn format(self: Value) void {
        switch (self) {
            .integer => |v| std.debug.print("Integer: {}\n", .{v}),
            .float => |v| std.debug.print("Float: {d:.2}\n", .{v}),
            .boolean => |v| std.debug.print("Boolean: {}\n", .{v}),
            .string => |v| std.debug.print("String: \"{s}\"\n", .{v}),
            .nothing => std.debug.print("Nothing\n", .{}),
        }
    }

    fn isNumeric(self: Value) bool {
        return switch (self) {
            .integer, .float => true,
            else => false,
        };
    }
};

pub fn main() !void {
    const values = [_]Value{
        Value{ .integer = 42 },
        Value{ .float = 3.14 },
        Value{ .boolean = true },
        Value{ .string = "hello" },
        Value.nothing,
    };

    for (values) |v| {
        v.format();
        std.debug.print("  Numeric: {}\n", .{v.isNumeric()});
    }
}

Pattern Matching with Switch

Switch on tagged unions for exhaustive handling.

const std = @import("std");

const Shape = union(enum) {
    circle: f64,
    rectangle: struct { width: f64, height: f64 },
    triangle: struct { base: f64, height: f64 },

    fn area(self: Shape) f64 {
        return switch (self) {
            .circle => |r| std.math.pi * r * r,
            .rectangle => |rect| rect.width * rect.height,
            .triangle => |tri| 0.5 * tri.base * tri.height,
        };
    }

    fn name(self: Shape) []const u8 {
        return switch (self) {
            .circle => "Circle",
            .rectangle => "Rectangle",
            .triangle => "Triangle",
        };
    }
};

pub fn main() !void {
    const shapes = [_]Shape{
        Shape{ .circle = 5.0 },
        Shape{ .rectangle = .{ .width = 10, .height = 3 } },
        Shape{ .triangle = .{ .base = 8, .height = 6 } },
    };

    for (shapes) |shape| {
        std.debug.print("{s}: area = {d:.2}\n", .{ shape.name(), shape.area() });
    }
}

Try It Yourself

const std = @import("std");

const JsonValue = union(enum) {
    number: f64,
    string: []const u8,
    boolean: bool,
    null_value,

    fn toString(self: JsonValue) void {
        switch (self) {
            .number => |n| std.debug.print("{d}", .{n}),
            .string => |s| std.debug.print("\"{s}\"", .{s}),
            .boolean => |b| std.debug.print("{}", .{b}),
            .null_value => std.debug.print("null", .{}),
        }
    }

    fn typeName(self: JsonValue) []const u8 {
        return switch (self) {
            .number => "number",
            .string => "string",
            .boolean => "boolean",
            .null_value => "null",
        };
    }
};

const KeyValue = struct {
    key: []const u8,
    value: JsonValue,
};

pub fn main() !void {
    const data = [_]KeyValue{
        .{ .key = "name", .value = JsonValue{ .string = "Alice" } },
        .{ .key = "age", .value = JsonValue{ .number = 30 } },
        .{ .key = "active", .value = JsonValue{ .boolean = true } },
        .{ .key = "deleted_at", .value = JsonValue.null_value },
    };

    std.debug.print("JSON object:\n", .{});
    for (data) |kv| {
        std.debug.print("  \"{s}\": ", .{kv.key});
        kv.value.toString();
        std.debug.print(" ({s})\n", .{kv.value.typeName()});
    }
}

Key Takeaways

Optional ?T is either a value or null — no null pointer surprises
Use if (optional) |value| for safe unwrapping
orelse provides a default when the optional is null
Tagged unions hold one of several types with the tag tracked at runtime
switch on unions is exhaustive — the compiler ensures you handle every variant
Unions can have methods, just like structs
Combine optionals and unions for expressive, safe data modeling

Pro Tip: Prefer optionals over sentinel values (like -1 or empty strings) to represent "no value." The type system forces callers to handle the null case, while a sentinel value can be silently ignored. When you need more than two states, upgrade from optional to a tagged union.