union

test.zig

Shell

$ zig test test.zig
1/1 test "simple union"... thread 793111 panic: access of inactive union field
/home/andy/Downloads/zig/docgen_tmp/test.zig:8:12: 0x207a4b in test "simple union" (test)
    payload.float = 12.34;
           ^
/home/andy/Downloads/zig/lib/std/special/test_runner.zig:80:28: 0x22f453 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/Downloads/zig/lib/std/start.zig:543:22: 0x227e4c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:495:12: 0x20926e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:409:17: 0x208306 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:322:5: 0x208112 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/8e4964e05ddaf866e77360a551b3c05b/test /home/andy/Downloads/zig/build-release/zig

You can activate another field by assigning the entire union:

test_simple_union.zig

const std = @import("std");
const expect = std.testing.expect;
const Payload = union {
    int: i64,
    boolean: bool,
};
    var payload = Payload{ .int = 1234 };
    try expect(payload.int == 1234);
    payload = Payload{ .float = 12.34 };
    try expect(payload.float == 12.34);
}

Shell

$ zig test test_simple_union.zig
1/1 test "simple union"... OK
All 1 tests passed.

In order to use with a union, it must be a Tagged union.

To initialize a union when the tag is a -known name, see @unionInit.

test_switch_tagged_union.zig

Shell

$ zig test test_switch_tagged_union.zig
1/3 test "switch on tagged union"... OK
2/3 test "get tag type"... OK
3/3 test "coerce to enum"... OK
All 3 tests passed.

In order to modify the payload of a tagged union in a switch expression, place a * before the variable name to make it a pointer:

test_switch_modify_tagged_union.zig

const std = @import("std");
const expect = std.testing.expect;
const ComplexTypeTag = enum {
    ok,
    not_ok,
};
const ComplexType = union(ComplexTypeTag) {
    ok: u8,
    not_ok: void,
};
test "modify tagged union in switch" {
    var c = ComplexType{ .ok = 42 };
    try expect(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);
        ComplexTypeTag.ok => |*value| value.* += 1,
        ComplexTypeTag.not_ok => unreachable,
    }
    try expect(c.ok == 43);
}

Shell

$ zig test test_switch_modify_tagged_union.zig
1/1 test "modify tagged union in switch"... OK
All 1 tests passed.

Unions can be made to infer the enum tag type. Further, unions can have methods just like structs and enums.

test_union_method.zig

$ zig test test_union_method.zig
1/1 test "union method"... OK
All 1 tests passed.

can be used to return a comptime [:0]const u8 value representing the field name:

test_tagName.zig

const std = @import("std");
const expect = std.testing.expect;
const Small2 = union(enum) {
    a: i32,
    b: bool,
    c: u8,
};
test "@tagName" {
    try expect(std.mem.eql(u8, @tagName(Small2.a), "a"));
}

Shell

$ zig test test_tagName.zig
1/1 test "@tagName"... OK
All 1 tests passed.

An extern union has memory layout guaranteed to be compatible with the target C ABI.