Tagged Unions and switch
Pattern-match over union variants.
Tagged Unions and switch is a free Zig Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Zig Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Remembering the Variant
A plain union forgets which field is active. A tagged union pairs the value with an enum tag that records the current variant.
Declaring a Tagged Union
You write union(enum) to let Zig generate a matching tag automatically, one tag name per field.
const Value = union(enum) { int: i64, text: []const u8 };The Tag Tracks the Field
Now the value carries its own tag, like .int or .text. The union always knows which variant it currently holds.
var v = Value{ .int = 7 };Switch over the Variants
Use switch on a tagged union to branch by variant. Each case names one tag and handles that shape of the value.
switch (v) { .int => {}, .text => {} }Capture the Payload
Add a capture with vertical bars to pull out the inner value of the active field, ready to use inside that branch.
switch (v) { .int => |n| useInt(n), .text => |s| useText(s) }Exhaustiveness Is Enforced
Zig requires every variant to be handled. Forget a case and the compiler stops you, so you never silently miss one.
The else Branch
When you want to handle the rest in one place, add an else branch to cover any variants you did not list explicitly.
switch (v) { .int => |n| useInt(n), else => {} }switch Is an Expression
A switch can produce a value, so each branch returns something. You assign the whole switch to a variable in one step.
const kind = switch (v) { .int => 1, .text => 2 };Mutate Through a Capture
Capture by pointer with |*field| when you want to change the payload in place rather than copy it out of the union.
switch (v) { .int => |*n| n.* += 1, else => {} }A Type-Safe Sum Type
Tagged unions are Zig's safe sum types: one value, many shapes, and a switch that the compiler proves you handled completely.
Perfect for Parsers and States
This pattern fits tokens, AST nodes, and state machines beautifully: model each case once and let switch route the logic.
Quick Check
What does writing union(enum) give you over a plain union?
Recap
You met tagged unions: union(enum) tracks the active variant. Switch over it, capture payloads with bars, and the compiler enforces every case. 🧩
Frequently asked questions
Is the “Tagged Unions and switch” lesson free?
Yes — the full text of “Tagged Unions and switch” is free to read here on the web, and the Zig Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Zig Academy course, upgrade to CoddyKit PRO.
What will I learn in “Tagged Unions and switch”?
Pattern-match over union variants. You practise Zig Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Zig Academy?
No prior experience is required. Zig Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Tagged Unions and switch” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Zig Academy lesson?
Yes. Every Zig Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.