enum

enums.zig

const assert = @import("std").debug.assert;
const mem = @import("std").mem;
// Declare an enum.
const Type = enum {
    Ok,
    NotOk,
};
// Declare a specific instance of the enum variant.
const c = Type.Ok;
// If you want access to the ordinal value of an enum, you
// can specify the tag type.
const Value = enum(u2) {
    Zero,
    One,
    Two,
};
// Now you can cast between u2 and Value.
// The ordinal value starts from 0, counting up for each member.
test "enum ordinal value" {
    assert(@enumToInt(Value.Zero) == 0);
    assert(@enumToInt(Value.One) == 1);
    assert(@enumToInt(Value.Two) == 2);
}
// You can override the ordinal value for an enum.
const Value2 = enum(u32) {
    Hundred = 100,
    Thousand = 1000,
    Million = 1000000,
};
test "set enum ordinal value" {
    assert(@enumToInt(Value2.Hundred) == 100);
    assert(@enumToInt(Value2.Thousand) == 1000);
    assert(@enumToInt(Value2.Million) == 1000000);
}
// Enums can have methods, the same as structs and unions.
// Enum methods are not special, they are only namespaced
// functions that you can call with dot syntax.
const Suit = enum {
    Clubs,
    Spades,
    Diamonds,
    Hearts,
    pub fn isClubs(self: Suit) bool {
        return self == Suit.Clubs;
    }
};
test "enum method" {
    const p = Suit.Spades;
    assert(!p.isClubs());
}
// An enum variant of different types can be switched upon.
const Foo = enum {
    String,
    Number,
    None,
};
test "enum variant switch" {
    const p = Foo.Number;
    const what_is_it = switch (p) {
        Foo.String => "this is a string",
        Foo.Number => "this is a number",
        Foo.None => "this is a none",
    };
    assert(mem.eql(u8, what_is_it, "this is a number"));
}
// @TagType can be used to access the integer tag type of an enum.
const Small = enum {
    One,
    Two,
    Three,
    Four,
};
test "@TagType" {
    assert(@TagType(Small) == u2);
}
// @typeInfo tells us the field count and the fields names:
test "@typeInfo" {
    assert(@typeInfo(Small).Enum.fields.len == 4);
    assert(mem.eql(u8, @typeInfo(Small).Enum.fields[1].name, "Two"));
}
// @tagName gives a []const u8 representation of an enum value:
test "@tagName" {
    assert(mem.eql(u8, @tagName(Small.Three), "Three"));
}

$ zig test enums.zig
1/7 test "enum ordinal value"...OK
2/7 test "set enum ordinal value"...OK
3/7 test "enum method"...OK
4/7 test "enum variant switch"...OK
5/7 test "@TagType"...OK
6/7 test "@typeInfo"...OK
7/7 test "@tagName"...OK
All 7 tests passed.

See also:

• @typeInfo
• @tagName
• @sizeOf

extern enum

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

test.zig

const Foo = enum { A, B, C };
export fn entry(foo: Foo) void { }

$ zig build-obj test.zig
./docgen_tmp/test.zig:2:22: error: parameter of type 'Foo' not allowed in function with calling convention 'C'
export fn entry(foo: Foo) void { 
                     ^

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

test.zig

const Foo = extern enum { A, B, C };
export fn entry(foo: Foo) void { }

$ zig build-obj test.zig

packed enum

By default, the size of enums is not guaranteed.

packed enum causes the size of the enum to be the same as the size of the integer tag type of the enum:

test.zig

const std = @import("std");
test "packed enum" {
    const Number = packed enum(u8) {
        One,
        Two,
        Three,
    };
    std.debug.assert(@sizeOf(Number) == @sizeOf(u8));
}

$ zig test test.zig
1/1 test "packed enum"...OK
All 1 tests passed.

This makes the enum eligible to be in a packed struct.

Enum Literals

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

test.zig

const std = @import("std");
const assert = std.debug.assert;
const Color = enum {
    Auto,
    Off,
    On,
};
test "enum literals" {
    const color1: Color = .Auto;
    const color2 = Color.Auto;
    assert(color1 == color2);
}
test "switch using enum literals" {
    const color = Color.On;
    const result = switch (color) {
        .Auto => false,
        .On => true,
        .Off => false,
    };
    assert(result);
}

$ zig test test.zig
1/2 test "enum literals"...OK
2/2 test "switch using enum literals"...OK
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

const std = @import("std");
const assert = std.debug.assert;
const Number = enum(u8) {
    One,
    Two,
    Three,
    _,
};
test "switch on non-exhaustive enum" {
    const number = Number.One;
    const result = switch (number) {
        .One => true,
        .Two,
        .Three => false,
        _ => false,
    };
    assert(result);
    const is_one = switch (number) {
        .One => true,
        else => false,
    };
    assert(is_one);
}

$ zig test test.zig
1/1 test "switch on non-exhaustive enum"...OK
All 1 tests passed.