union

    test.zig

    1. $ zig test test.zig
    2. 1/1 test "simple union"...access of inactive union field
    3. /home/andy/dev/zig/docgen_tmp/test.zig:8:12: 0x2055b5 in test "simple union" (test)
    4.     payload.Float = 12.34;
    5.            ^
    6. /home/andy/dev/zig/lib/std/special/test_runner.zig:13:25: 0x2283d1 in std.special.main (test)
    7.         if (test_fn.func()) |_| {
    8.                         ^
    9. /home/andy/dev/zig/lib/std/special/start.zig:204:37: 0x227245 in std.special.posixCallMainAndExit (test)
    10.             const result = root.main() catch |err| {
    11.                                     ^
    12. /home/andy/dev/zig/lib/std/special/start.zig:102:5: 0x2270bf in std.special._start (test)
    13.     @noInlineCall(posixCallMainAndExit);
    14.     ^
    16. Tests failed. Use the following command to reproduce the failure:
    17. /home/andy/dev/zig/docgen_tmp/test

    You can activate another field by assigning the entire union:

    test.zig

    1. const std = @import("std");
    2. const assert = std.debug.assert;
    4. const Payload = union {
    5.     Int: i64,
    6.     Float: f64,
    7.     Bool: bool,
    8. test "simple union" {
    9.     var payload = Payload{ .Int = 1234 };
    11.     payload = Payload{ .Float = 12.34 };
    12.     assert(payload.Float == 12.34);
    13. }
    1. $ zig test test.zig
    2. 1/1 test "simple union"...OK
    3. All tests passed.

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

    Unions can be declared with an enum tag type. This turns the union into a tagged union, which makes it eligible to use with expressions. One can use @TagType to obtain the enum type from the union type.

    test.zig

    1. $ zig test test.zig
    2. 1/2 test "switch on tagged union"...OK
    3. 2/2 test "@TagType"...OK
    4. All 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.zig

    1. const std = @import("std");
    2. const assert = std.debug.assert;
    4. const ComplexTypeTag = enum {
    5.     Ok,
    6.     NotOk,
    7. };
    8. const ComplexType = union(ComplexTypeTag) {
    9.     Ok: u8,
    10.     NotOk: void,
    11. };
    13. test "modify tagged union in switch" {
    14.     var c = ComplexType{ .Ok = 42 };
    17.         ComplexTypeTag.Ok => |*value| value.* += 1,
    18.         ComplexTypeTag.NotOk => unreachable,
    19.     }
    21.     assert(c.Ok == 43);
    22. }
    1. $ zig test test.zig
    2. 1/1 test "modify tagged union in switch"...OK
    3. All tests passed.

    test.zig

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

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

    test.zig

    1. const std = @import("std");
    2. const assert = std.debug.assert;
    4. const Small2 = union(enum) {
    5.     A: i32,
    6.     B: bool,
    7.     C: u8,
    8. };
    9. test "@tagName" {
    10.     assert(std.mem.eql(u8, @tagName(Small2.C), "C"));
    11. }
    1. $ zig test test.zig
    2. 1/1 test "@tagName"...OK

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

    A packed union has well-defined in-memory layout and is eligible to be in a packed struct.