enum
const expect = @import("std").testing.expect;
const expectEqual = @import("std").testing.expectEqual;
const expectEqualStrings = @import("std").testing.expectEqualStrings;
const mem = @import("std").mem;
// 声明枚举。
const Type = enum {
ok,
not_ok,
};
// 声明特定枚举字段。
const c = Type.ok;
// 如果需要访问枚举的序数值,
// 可以指定标记类型。
const Value = enum(u2) {
zero,
one,
two,
};
// 现在可以在 u2 和 Value 之间转换。
// 序数值从 0 开始,相对于前一成员递增 1。
test "enum ordinal value" {
try expectEqual(0, @backingInt(Value.zero));
try expectEqual(1, @backingInt(Value.one));
try expectEqual(2, @backingInt(Value.two));
}
// 可以覆盖枚举的序数值。
const Value2 = enum(u32) {
hundred = 100,
thousand = 1000,
million = 1000000,
};
test "set enum ordinal value" {
try expectEqual(100, @backingInt(Value2.hundred));
try expectEqual(1000, @backingInt(Value2.thousand));
try expectEqual(1000000, @backingInt(Value2.million));
}
// 也可以只覆盖部分值。
const Value3 = enum(u4) {
a,
b = 8,
c,
d = 4,
e,
};
test "enum implicit ordinal values and overridden values" {
try expectEqual(0, @backingInt(Value3.a));
try expectEqual(8, @backingInt(Value3.b));
try expectEqual(9, @backingInt(Value3.c));
try expectEqual(4, @backingInt(Value3.d));
try expectEqual(5, @backingInt(Value3.e));
}
// 与结构体和联合一样,枚举可以有方法。
// 枚举方法并不特殊,只是命名空间中的函数,
// 可以使用点语法调用。
const Suit = enum {
clubs,
spades,
diamonds,
hearts,
pub fn isClubs(self: Suit) bool {
return self == Suit.clubs;
}
};
test "enum method" {
const p = Suit.spades;
try expect(!p.isClubs());
}
// 可以对枚举执行 switch。
const Foo = enum {
string,
number,
none,
};
test "enum 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",
};
try expectEqualStrings(what_is_it, "this is a number");
}
// 可以用 @typeInfo 访问枚举的整数标记类型。
const Small = enum {
one,
two,
three,
four,
};
test "std.meta.Tag" {
try expectEqual(u2, @typeInfo(Small).@"enum".tag_type);
}
// @typeInfo 提供字段数量和字段名称:
test "@typeInfo" {
try expectEqual(4, @typeInfo(Small).@"enum".field_names.len);
try expectEqualStrings(@typeInfo(Small).@"enum".field_names[1], "two");
}
// @tagName 返回枚举值的 [:0]const u8 表示:
test "@tagName" {
try expectEqualStrings(@tagName(Small.three), "three");
}
// 空枚举无法实例化,其标记类型始终为 noreturn。
const Empty = enum {};
test "empty enum" {
try expectEqual(noreturn, @typeInfo(Empty).@"enum".tag_type);
}$ zig test test_enums.zig
1/9 test_enums.test.enum ordinal value...OK
2/9 test_enums.test.set enum ordinal value...OK
3/9 test_enums.test.enum implicit ordinal values and overridden values...OK
4/9 test_enums.test.enum method...OK
5/9 test_enums.test.enum switch...OK
6/9 test_enums.test.std.meta.Tag...OK
7/9 test_enums.test.@typeInfo...OK
8/9 test_enums.test.@tagName...OK
9/9 test_enums.test.empty enum...OK
All 9 tests passed.
另见:
extern enum
默认情况下,不保证枚举兼容 C ABI:
const Foo = enum { a, b, c };
export fn entry(foo: Foo) void {
_ = foo;
}$ zig build-obj enum_export_error.zig -target x86_64-linux
/home/andy/src/zig/doc/langref/enum_export_error.zig:2:17: error: parameter of type 'enum_export_error.Foo' not allowed in function with calling convention 'x86_64_sysv'
export fn entry(foo: Foo) void {
^~~~~~~~
/home/andy/src/zig/doc/langref/enum_export_error.zig:1:13: note: integer tag type of enum is inferred
const Foo = enum { a, b, c };
^~~~~~~~~~~~~~~~
/home/andy/src/zig/doc/langref/enum_export_error.zig:1:13: note: consider explicitly specifying the integer tag type
/home/andy/src/zig/doc/langref/enum_export_error.zig:1:13: note: enum declared here
referenced by:
root: /home/andy/src/zig/lib/std/start.zig:13:22
comptime: /home/andy/src/zig/lib/std/start.zig:20:9
2 reference(s) hidden; use '-freference-trace=4' to see all references
若要使枚举兼容 C ABI,应显式提供枚举的标记类型:
const Foo = enum(c_int) { a, b, c };
export fn entry(foo: Foo) void {
_ = foo;
}$ zig build-obj enum_export.zig
枚举字面量
枚举字面量允许只指定枚举字段名,不指定枚举类型:
const std = @import("std");
const expect = std.testing.expect;
const expectEqual = std.testing.expectEqual;
const Color = enum {
auto,
off,
on,
};
test "enum literals" {
const color1: Color = .auto;
const color2 = Color.auto;
try expectEqual(color1, color2);
}
test "switch using enum literals" {
const color = Color.on;
const result = switch (color) {
.auto => false,
.on => true,
.off => false,
};
try expect(result);
}$ zig test test_enum_literals.zig
1/2 test_enum_literals.test.enum literals...OK
2/2 test_enum_literals.test.switch using enum literals...OK
All 2 tests passed.
非穷尽枚举
在末尾添加 _ 字段即可创建非穷尽枚举。该枚举必须指定标记类型,且不能用尽所有可能的枚举值。
对非穷尽枚举调用 @fromBackingInt,始终会得到有效的枚举值。
对非穷尽枚举执行 switch 时,可以使用 _ 分支替代 else 分支。使用 _ 分支时,如果 switch 未处理所有已知标记名称,编译器会报错。
const std = @import("std");
const expect = std.testing.expect;
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,
};
try expect(result);
const is_one = switch (number) {
.one => true,
else => false,
};
try expect(is_one);
}$ zig test test_switch_non-exhaustive.zig
1/1 test_switch_non-exhaustive.test.switch on non-exhaustive enum...OK
All 1 tests passed.