enum

enums.zig

  1. const expect = @import("std").testing.expect;
  2. const mem = @import("std").mem;
  4. // Declare an enum.
  5. const Type = enum {
  6.     ok,
  7.     not_ok,
  8. };
  10. // Declare a specific instance of the enum variant.
  11. const c = Type.ok;
  13. // If you want access to the ordinal value of an enum, you
  14. // can specify the tag type.
  15. const Value = enum(u2) {
  16.     zero,
  17.     one,
  18.     two,
  19. };
  21. // Now you can cast between u2 and Value.
  22. // The ordinal value starts from 0, counting up for each member.
  23. test "enum ordinal value" {
  24.     try expect(@enumToInt(Value.zero) == 0);
  25.     try expect(@enumToInt(Value.one) == 1);
  26.     try expect(@enumToInt(Value.two) == 2);
  27. }
  29. // You can override the ordinal value for an enum.
  30. const Value2 = enum(u32) {
  31.     hundred = 100,
  32.     thousand = 1000,
  33.     million = 1000000,
  34. };
  35. test "set enum ordinal value" {
  36.     try expect(@enumToInt(Value2.hundred) == 100);
  37.     try expect(@enumToInt(Value2.thousand) == 1000);
  38.     try expect(@enumToInt(Value2.million) == 1000000);
  39. }
  41. // Enums can have methods, the same as structs and unions.
  42. // Enum methods are not special, they are only namespaced
  43. // functions that you can call with dot syntax.
  44. const Suit = enum {
  45.     clubs,
  46.     spades,
  47.     diamonds,
  48.     hearts,
  50.     pub fn isClubs(self: Suit) bool {
  51.         return self == Suit.clubs;
  52.     }
  53. };
  54. test "enum method" {
  55.     const p = Suit.spades;
  56.     try expect(!p.isClubs());
  57. }
  59. // An enum variant of different types can be switched upon.
  60. const Foo = enum {
  61.     string,
  62.     number,
  63.     none,
  64. };
  65. test "enum variant switch" {
  66.     const p = Foo.number;
  67.     const what_is_it = switch (p) {
  68.         Foo.string => "this is a string",
  69.         Foo.number => "this is a number",
  70.         Foo.none => "this is a none",
  71.     };
  72.     try expect(mem.eql(u8, what_is_it, "this is a number"));
  73. }
  75. // @typeInfo can be used to access the integer tag type of an enum.
  76. const Small = enum {
  77.     one,
  78.     two,
  79.     three,
  80.     four,
  81. };
  82. test "std.meta.Tag" {
  83.     try expect(@typeInfo(Small).Enum.tag_type == u2);
  84. }
  86. // @typeInfo tells us the field count and the fields names:
  87. test "@typeInfo" {
  88.     try expect(@typeInfo(Small).Enum.fields.len == 4);
  89.     try expect(mem.eql(u8, @typeInfo(Small).Enum.fields[1].name, "two"));
  90. }
  92. // @tagName gives a []const u8 representation of an enum value:
  93. test "@tagName" {
  94.     try expect(mem.eql(u8, @tagName(Small.three), "three"));
  95. }
  1. $ zig test enums.zig
  2. Test [1/7] test "enum ordinal value"... 
  3. Test [2/7] test "set enum ordinal value"... 
  4. Test [3/7] test "enum method"... 
  5. Test [4/7] test "enum variant switch"... 
  6. Test [5/7] test "std.meta.Tag"... 
  7. Test [6/7] test "@typeInfo"... 
  8. Test [7/7] test "@tagName"... 
  10. All 7 tests passed.

See also:

extern enum

By default, enums are not guaranteed to be compatible with the C ABI:

test.zig

  1. const Foo = enum { a, b, c };
  2. export fn entry(foo: Foo) void { }
  1. $ zig build-obj test.zig
  2. ./docgen_tmp/test.zig:2:22: error: parameter of type 'Foo' not allowed in function with calling convention 'C'
  3. export fn entry(foo: Foo) void { }
  4.                      ^

For a C-ABI-compatible enum, use extern enum:

test.zig

  1. const Foo = extern enum { a, b, c };
  2. export fn entry(foo: Foo) void { }
  1. $ zig build-obj test.zig

Enum Literals

Enum literals allow specifying the name of an enum field without specifying the enum type:

test.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. const Color = enum {
  5.     auto,
  6.     off,
  7.     on,
  8. };
  10. test "enum literals" {
  11.     const color1: Color = .auto;
  12.     const color2 = Color.auto;
  13.     try expect(color1 == color2);
  14. }
  16. test "switch using enum literals" {
  17.     const color = Color.on;
  18.     const result = switch (color) {
  19.         .auto => false,
  20.         .on => true,
  21.         .off => false,
  22.     };
  23.     try expect(result);
  24. }
  1. $ zig test test.zig
  2. Test [1/2] test "enum literals"... 
  3. Test [2/2] test "switch using enum literals"... 
  5. All 2 tests passed.

Non-exhaustive enum

A Non-exhaustive enum can be created by adding a trailing ‘_‘ field. It must specify a tag type and cannot consume every enumeration value.

@intToEnum on a non-exhaustive enum cannot fail.

A switch on a non-exhaustive enum can include a ‘_‘ prong as an alternative to an else prong with the difference being that it makes it a compile error if all the known tag names are not handled by the switch.

test.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. const Number = enum(u8) {
  5.     one,
  6.     two,
  7.     three,
  8.     _,
  9. };
  11. test "switch on non-exhaustive enum" {
  12.     const number = Number.one;
  13.     const result = switch (number) {
  14.         .one => true,
  15.         .two,
  16.         .three => false,
  17.         _ => false,
  18.     };
  19.     try expect(result);
  20.     const is_one = switch (number) {
  21.         .one => true,
  22.         else => false,
  23.     };
  24.     try expect(is_one);
  25. }
  1. $ zig test test.zig
  2. Test [1/1] test "switch on non-exhaustive enum"... 
  4. All 1 tests passed.