liveBook · Manning

Error set

As explained in Systems Programming with Zig

An error set is the statically specified set of error values that a function may produce.

A file-reading function can fail because a file is unreadable or memory runs out. In Zig, an error set is a type that names possible error values, making failures part of a function’s contract. The compiler can check assumptions about those failures, and callers must handle or explicitly discard errors. section 3.2.2 section 3.4.1 section 1.3.1

const InvalidLengthError = error {
    TooLong,
    TooShort,
};

This set names two possible username-length errors. An error is a value: for example, error.TooLong can be stored in a variable of type InvalidLengthError. section 3.2.2

A value from a narrower error set can coerce to a wider set when all its possible errors are contained in the wider set. For example, error{TooLong} can coerce to InvalidLengthError. The special set anyerror includes every possible error. section 3.2.2

Listing 3.2 Fibonacci but checked
const FibonacciError = error { OverFibonacciLimit };

const fibonacci_limit = 30;

fn fibonacci(n: usize) FibonacciError!i32 { #1
    if (n == 0) {
        return 0;
    } else if (n == 1) {
        return 1;
    } else if (n > fibonacci_limit) {
        return error.OverFibonacciLimit; #2
    }
    return try fibonacci(n - 1) + try fibonacci(n - 2); #3
}

The ! operator combines FibonacciError with an i32 payload into an error union. The function returns error.OverFibonacciLimit for an excessive input; try propagates errors from recursive calls. section 3.2.2

A function can omit the error set from its error union return type and let the compiler infer it. Writing the set explicitly when feasible makes the possible failures clearer to readers and callers. section 3.2.2

Listing 4.9 Invalid word errors
const InvalidWordError = error {
    BadLength,
    NotInWordlist,
    NotWordLadder,
};

fn validateWord(
    input: []const u8,
    last_word: [4]u8,
) InvalidWordError![4]u8 { #1
    // validation code ...
}

Word validation gives each failure its own error: bad length, a missing wordlist entry, or an invalid word-ladder move. Returning errors instead of printing inside validation keeps that logic separate from the console and lets callers choose useful messages. section 4.1.5

To audit a file utility, look for try and return, then check the called functions’ error sets in the standard library documentation. An unreadable file may deserve a helpful message, while returning an error from main may be acceptable for a rare stdout failure. section 3.4.1

Error sets also shape interpreter APIs. A memory-reading helper can return ReadOutOfBounds, while the interpreter’s step function names that failure alongside UnknownInstruction and propagates the read error with try. section 6.3.3

How Systems Programming with Zig covers it

How deep it goes
Explains declarations, values, subset coercion, inference, error unions, and propagation through practical functions.
Examples
Uses Fibonacci input limits, word-ladder validation, file-reading failures, and CHIP-8 memory bounds to illustrate error sets.
What you can do after
Apply error sets in Zig to specify failures, propagate errors, and guide handling decisions.
How it connects
Connects error sets to error unions, type coercion, error propagation, and separation of concerns.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Systems Programming with Zig. The section links point to the parts of the book it draws on.