union

A bare union defines a set of possible types that a value can be as a list of fields. Only one field can be active at a time. The in-memory representation of bare unions is not guaranteed. Bare unions cannot be used to reinterpret memory. For that, use @ptrCast, or use an extern union or a packed union which have guaranteed in-memory layout. Accessing the non-active field is safety-checked Undefined Behavior:

test_wrong_union_access.zig

  1. const Payload = union {
  2. int: i64,
  3. float: f64,
  4. boolean: bool,
  5. };
  6. test "simple union" {
  7. var payload = Payload{ .int = 1234 };
  8. payload.float = 12.34;
  9. }

Shell

  1. $ zig test test_wrong_union_access.zig
  2. 1/1 test_wrong_union_access.test.simple union... thread 987122 panic: access of union field 'float' while field 'int' is active
  3. /home/ci/actions-runner/_work/zig-bootstrap/zig/docgen_tmp/test_wrong_union_access.zig:8:12: 0x1038f27 in test.simple union (test)
  4. payload.float = 12.34;
  5. ^
  6. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:158:25: 0x10440c2 in mainTerminal (test)
  7. if (test_fn.func()) |_| {
  8. ^
  9. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:35:28: 0x103a11b in main (test)
  10. return mainTerminal();
  11. ^
  12. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:501:22: 0x10394b9 in posixCallMainAndExit (test)
  13. root.main();
  14. ^
  15. /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:253:5: 0x1039021 in _start (test)
  16. asm volatile (switch (native_arch) {
  17. ^
  18. ???:?:?: 0x0 in ??? (???)
  19. error: the following test command crashed:
  20. /home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/5285249bc32c82ff3a07356dfb83fe43/test

You can activate another field by assigning the entire union:

test_simple_union.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const Payload = union {
  4. int: i64,
  5. float: f64,
  6. boolean: bool,
  7. };
  8. test "simple union" {
  9. var payload = Payload{ .int = 1234 };
  10. try expect(payload.int == 1234);
  11. payload = Payload{ .float = 12.34 };
  12. try expect(payload.float == 12.34);
  13. }

Shell

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

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

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

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 switch expressions. Tagged unions coerce to their tag type: Type Coercion: Unions and Enums.

test_tagged_union.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const ComplexTypeTag = enum {
  4. ok,
  5. not_ok,
  6. };
  7. const ComplexType = union(ComplexTypeTag) {
  8. ok: u8,
  9. not_ok: void,
  10. };
  11. test "switch on tagged union" {
  12. const c = ComplexType{ .ok = 42 };
  13. try expect(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);
  14. switch (c) {
  15. ComplexTypeTag.ok => |value| try expect(value == 42),
  16. ComplexTypeTag.not_ok => unreachable,
  17. }
  18. }
  19. test "get tag type" {
  20. try expect(std.meta.Tag(ComplexType) == ComplexTypeTag);
  21. }

Shell

  1. $ zig test test_tagged_union.zig
  2. 1/2 test_tagged_union.test.switch on tagged union... OK
  3. 2/2 test_tagged_union.test.get tag type... OK
  4. All 2 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

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const ComplexTypeTag = enum {
  4. ok,
  5. not_ok,
  6. };
  7. const ComplexType = union(ComplexTypeTag) {
  8. ok: u8,
  9. not_ok: void,
  10. };
  11. test "modify tagged union in switch" {
  12. var c = ComplexType{ .ok = 42 };
  13. switch (c) {
  14. ComplexTypeTag.ok => |*value| value.* += 1,
  15. ComplexTypeTag.not_ok => unreachable,
  16. }
  17. try expect(c.ok == 43);
  18. }

Shell

  1. $ zig test test_switch_modify_tagged_union.zig
  2. 1/1 test_switch_modify_tagged_union.test.modify tagged union in switch... OK
  3. 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

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const Variant = union(enum) {
  4. int: i32,
  5. boolean: bool,
  6. // void can be omitted when inferring enum tag type.
  7. none,
  8. fn truthy(self: Variant) bool {
  9. return switch (self) {
  10. Variant.int => |x_int| x_int != 0,
  11. Variant.boolean => |x_bool| x_bool,
  12. Variant.none => false,
  13. };
  14. }
  15. };
  16. test "union method" {
  17. var v1 = Variant{ .int = 1 };
  18. var v2 = Variant{ .boolean = false };
  19. try expect(v1.truthy());
  20. try expect(!v2.truthy());
  21. }

Shell

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

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

test_tagName.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const Small2 = union(enum) {
  4. a: i32,
  5. b: bool,
  6. c: u8,
  7. };
  8. test "@tagName" {
  9. try expect(std.mem.eql(u8, @tagName(Small2.a), "a"));
  10. }

Shell

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

extern union

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

See also:

packed union

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

Anonymous Union Literals

Anonymous Struct Literals syntax can be used to initialize unions without specifying the type:

test_anonymous_union.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  3. const Number = union {
  4. int: i32,
  5. float: f64,
  6. };
  7. test "anonymous union literal syntax" {
  8. const i: Number = .{ .int = 42 };
  9. const f = makeNumber();
  10. try expect(i.int == 42);
  11. try expect(f.float == 12.34);
  12. }
  13. fn makeNumber() Number {
  14. return .{ .float = 12.34 };
  15. }

Shell

  1. $ zig test test_anonymous_union.zig
  2. 1/1 test_anonymous_union.test.anonymous union literal syntax... OK
  3. All 1 tests passed.