内置函数
内置函数由编译器提供,以 @ 为前缀。参数上的 comptime 关键字表示该参数必须在编译时已知。
@addrSpaceCast
@addrSpaceCast(ptr: anytype) anytype
将指针从一个地址空间转换到另一个地址空间。新的地址空间根据结果类型推导。取决于当前目标平台与地址空间,这种转换可能不执行操作,也可能执行复杂操作,或不合法。转换合法时,结果指针与操作数指针指向同一内存位置。在相同地址空间之间转换指针始终合法。
@addWithOverflow
@addWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
执行 a + b,并返回一个元组,其中包含结果和一个可能的溢出位。
@alignCast
@alignCast(ptr: anytype) anytype
ptr 可以是 *T、?*T 或 []T。此函数改变指针的对齐要求,具体对齐值根据结果类型推导。
生成的代码会添加指针对齐安全检查,确保指针满足所承诺的对齐要求。
@alignOf
@alignOf(comptime T: type) comptime_int
返回此类型在当前目标平台上匹配 C ABI 时应采用的字节对齐值。当指针子类型采用此对齐值时,可以从指针类型中省略对齐说明。
const assert = @import("std").debug.assert;
comptime {
assert(*u32 == *align(@alignOf(u32)) u32);
}
结果是依赖目标平台的编译时常量,保证小于或等于 @sizeOf(T)。
另见:
@as
@as(comptime T: type, expression) T
执行类型强制转换。只有转换无歧义且安全时才允许使用;条件允许时,这是类型之间转换的首选方式。
@atomicLoad
@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T
此内置函数对指向 T 的指针执行原子解引用,并返回读取的值。
T 必须是指针、bool、浮点数、整数、枚举或紧凑结构体。
可通过 @import("std").lang.AtomicOrder 找到 AtomicOrder。
另见:
@atomicRmw
@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T
此内置函数对指向 T 的指针解引用,原子地修改其值,并返回修改前的值。
T 必须是指针、bool、浮点数、整数、枚举或紧凑结构体。
可通过 @import("std").lang.AtomicOrder 找到 AtomicOrder。
可通过 @import("std").lang.AtomicRmwOp 找到 AtomicRmwOp。
另见:
@atomicStore
@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void
此内置函数对指向 T 的指针解引用,并原子地存储给定值。
T 必须是指针、bool、浮点数、整数、枚举或紧凑结构体。
可通过 @import("std").lang.AtomicOrder 找到 AtomicOrder。
另见:
@backingInt
@backingInt(enum_or_bitpack: T) BackingInt(T)
将 enum、packed struct 或 packed union 值转换为其底层整数。
也适用于标记联合,操作的是当前活动枚举标记的值。
另见:
@bitCast
@bitCast(value: anytype) anytype
将一种类型的值转换为另一种类型。返回类型为推导出的结果类型。
断言 @sizeOf(@TypeOf(value)) == @sizeOf(DestType)。
断言 @typeInfo(DestType) != .pointer。如果需要进行这种转换,请使用 @ptrCast 或 @ptrFromInt。
例如,可以用于以下操作:
- 将
f32转换为u32位表示 - 将
i32转换为u32,保留二进制补码表示
如果 value 在编译时已知,就可以在编译时使用。对布局未定义的值执行位转换会产生编译错误;因此,除了指针、错误集合等已有专用转换内置函数的类型之外,普通结构体、错误联合、切片、可选类型以及其他没有明确内存布局的类型,也不能用于此操作。
尝试将没有对应标记值的整数转换为 enum,会引发带安全检查的非法行为。
另见:
@bitOffsetOf
@bitOffsetOf(comptime T: type, comptime field_name: []const u8) comptime_int
返回字段相对于所属结构体的位偏移。
对于非紧凑结构体,该偏移始终能被 8 整除。对于紧凑结构体,未按字节对齐的字段可能共享字节偏移,但具有不同位偏移。
另见:
@bitSizeOf
@bitSizeOf(comptime T: type) comptime_int
返回当 T 作为紧凑结构体或联合字段时,在内存中存储它所需的位数。结果是依赖目标平台的编译时常量。
此函数衡量运行时大小。对于 comptime_int、type 等不允许在运行时使用的类型,结果为 0。
另见:
@branchHint
@branchHint(hint: BranchHint) void
向优化器提示某个控制流分支被执行到的可能性。
可通过 @import("std").lang.BranchHint 找到 BranchHint。
此函数只能作为控制流分支的第一条语句,或函数中的第一条语句。
@breakpoint
@breakpoint() void
插入平台相关的调试陷阱指令,使调试器在此处中断。与 @trap() 不同,恢复程序后可以继续执行此位置之后的代码。
此函数仅在函数作用域内有效。
另见:
@mulAdd
@mulAdd(comptime T: type, a: T, b: T, c: T) T
融合乘加,类似于 (a * b) + c,但只舍入一次,因此精度更高。
@byteSwap
@byteSwap(operand: anytype) T
@TypeOf(operand) 必须是位数能被 8 整除的整数类型或整数向量类型。
交换整数的字节顺序,将大端整数变为小端整数,也将小端整数变为大端整数。
注意,对于与字节序有关的内存布局,整数类型应关联到 @sizeOf 报告的字节数。以 u24 为例,@sizeOf(u24) == 4,表示内存中的 u24 占 4 字节,大小端系统之间交换的也是这 4 个字节。但如果将 T 指定为 u24,则只反转 3 个字节。
@bitReverse
@bitReverse(integer: anytype) T
@TypeOf(anytype) 接受任意整数类型或整数向量类型。
反转整数值的位模式,包含符号位(若有)。
例如,0b10110110(u8 = 182、i8 = -74)变为 0b01101101(u8 = 109、i8 = 109)。
@offsetOf
@offsetOf(comptime T: type, comptime field_name: []const u8) comptime_int
返回字段相对于所属结构体的字节偏移。
另见:
@call
@call(modifier: std.lang.CallModifier, function: anytype, args: anytype) anytype
调用函数,与在表达式后添加圆括号进行调用相同:
const expectEqual = @import("std").testing.expectEqual;
test "noinline function call" {
try expectEqual(12, @call(.auto, add, .{ 3, 9 }));
}
fn add(a: i32, b: i32) i32 {
return a + b;
}$ zig test test_call_builtin.zig
1/1 test_call_builtin.test.noinline function call...OK
All 1 tests passed.
@call 比普通函数调用语法更灵活。下面列出 CallModifier 枚举:
pub const CallModifier = enum {
/// 等价于函数调用语法。
auto,
/// 阻止尾调用优化,保证返回地址
/// 指向本调用点,而非本调用点所属函数的
/// 调用点。如果此调用因其他原因必须为尾调用
/// 或必须内联,则改为产生编译错误。
never_tail,
/// 保证此调用不会内联。如果此调用因其他原因
/// 必须内联,则改为产生编译错误。
never_inline,
/// 断言该函数调用不会挂起,使非异步函数
/// 能够调用异步函数。
no_suspend,
/// 保证此调用使用尾调用优化生成。
/// 无法做到时,改为产生编译错误。
always_tail,
/// 保证此调用在调用点内联。
/// 无法做到时,改为产生编译错误。
always_inline,
/// 在编译时求值此调用。如果无法在编译时
/// 完成调用,则改为产生编译错误。
compile_time,
};@clz
@clz(operand: anytype) anytype
@TypeOf(operand) 必须是整数类型或整数向量类型。
计算整数从最高有效位开始连续为零的位数,即“前导零计数”。
返回类型是无符号整数或无符号整数向量,使用足以表示该整数类型位数的最少位数。
如果 operand 为零,@clz 返回整数类型 T 的位宽。
另见:
@cmpxchgStrong
@cmpxchgStrong(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T
执行强原子比较交换操作;当前值等于给定预期值时返回 null。它等价于以下代码,但整个过程为原子操作:
fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_value: T) ?T {
const old_value = ptr.*;
if (old_value == expected_value) {
ptr.* = new_value;
return null;
} else {
return old_value;
}
}在重试循环中使用 cmpxchg 时,@cmpxchgWeak 是更好的选择,因为机器指令可以更高效地实现它。
T 必须是指针、bool、整数、枚举或紧凑结构体。
@typeInfo(@TypeOf(ptr)).pointer.alignment 必须为 >= @sizeOf(T).
可通过 @import("std").lang.AtomicOrder 找到 AtomicOrder。
另见:
@cmpxchgWeak
@cmpxchgWeak(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T
执行弱原子比较交换操作;当前值等于给定预期值时返回 null。它等价于以下代码,但整个过程为原子操作:
fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_value: T) ?T {
const old_value = ptr.*;
if (old_value == expected_value and usuallyTrueButSometimesFalse()) {
ptr.* = new_value;
return null;
} else {
return old_value;
}
}在重试循环中使用 cmpxchg 时,偶发失败不会造成问题,因此 cmpxchgWeak 是更好的选择,因为机器指令可以更高效地实现它。如果需要更强保证,则使用 @cmpxchgStrong。
T 必须是指针、bool、整数、枚举或紧凑结构体。
@typeInfo(@TypeOf(ptr)).pointer.alignment 必须为 >= @sizeOf(T).
可通过 @import("std").lang.AtomicOrder 找到 AtomicOrder。
另见:
@compileError
@compileError(comptime msg: []const u8) noreturn
对该函数进行语义分析时,会产生消息为 msg 的编译错误。
有多种方式可以让代码不接受语义检查,例如将 if 或 switch 与编译时常量结合,以及使用 comptime 函数。
@compileLog
@compileLog(...) void
此函数在编译时打印传入的参数。
为避免无意中将编译日志语句遗留在代码库中,构建会添加一条指向该日志语句的编译错误。该错误阻止生成代码,但不会以其他方式干扰分析。
此函数可用于对编译时执行的代码进行“printf 调试”。
const print = @import("std").debug.print;
const num1 = blk: {
var val1: i32 = 99;
@compileLog("comptime val1 = ", val1);
val1 = val1 + 1;
break :blk val1;
};
test "main" {
@compileLog("comptime in main");
print("Runtime in main, num1 = {}.\n", .{num1});
}$ zig test test_compileLog_builtin.zig
/home/andy/src/zig/doc/langref/test_compileLog_builtin.zig:5:5: error: found compile log statement
@compileLog("comptime val1 = ", val1);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/andy/src/zig/doc/langref/test_compileLog_builtin.zig:11:5: note: also here
@compileLog("comptime in main");
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
referenced by:
test.main: /home/andy/src/zig/doc/langref/test_compileLog_builtin.zig:13:46
Compile Log Output:
@as(*const [16:0]u8, "comptime val1 = "), @as(i32, 99)
@as(*const [16:0]u8, "comptime in main")
@constCast
@constCast(value: anytype) DestType
移除指针的 const 限定符。
@ctz
@ctz(operand: anytype) anytype
@TypeOf(operand) 必须是整数类型或整数向量类型。
计算整数从最低有效位开始连续为零的位数,即“尾随零计数”。
返回类型是无符号整数或无符号整数向量,使用足以表示该整数类型位数的最少位数。
如果 operand 为零,@ctz 返回整数类型 T 的位宽。
另见:
@cVaArg
@cVaArg(operand: *std.lang.VaList, comptime T: type) T
实现 C 宏 va_arg。
另见:
@cVaCopy
@cVaCopy(src: *std.lang.VaList) std.lang.VaList
实现 C 宏 va_copy。
另见:
@cVaEnd
@cVaEnd(src: *std.lang.VaList) void
实现 C 宏 va_end。
另见:
@cVaStart
@cVaStart() std.lang.VaList
实现 C 宏 va_start,仅可用于可变参数函数内部。
另见:
@divExact
@divExact(numerator: T, denominator: T) T
精确除法。调用者保证 denominator != 0 且 @divTrunc(numerator, denominator) * denominator == numerator。
@divExact(6, 3) == 2@divExact(a, b) * b == a
如需可能返回错误码的函数,使用 @import("std").math.divExact。
另见:
@divFloor
@divFloor(numerator: T, denominator: T) T
向下取整除法,朝负无穷舍入。对于无符号整数,与 numerator / denominator 相同。调用者保证 denominator != 0 且 !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1)。
@divFloor(-5, 3) == -2(@divFloor(a, b) * b) + @mod(a, b) == a
如需可能返回错误码的函数,使用 @import("std").math.divFloor。
另见:
@divTrunc
@divTrunc(numerator: T, denominator: T) T
截断除法,朝零舍入。对于无符号整数,与 numerator / denominator 相同。调用者保证 denominator != 0 且 !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1)。
@divTrunc(-5, 3) == -1(@divTrunc(a, b) * b) + @rem(a, b) == a
如需可能返回错误码的函数,使用 @import("std").math.divTrunc。
另见:
@divCeil
@divCeil(numerator: T, denominator: T) T
向上取整除法,朝正无穷舍入。调用者保证 denominator != 0 且 !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1)。
@divCeil(5, 3) == 2@divCeil(-5, 3) == -1
如需可能返回错误码的函数,使用 @import("std").math.divCeil。
另见:
@embedFile
@embedFile(comptime path: []const u8) *const [N:0]u8
返回编译时常量指针,指向以 null 结尾的定长数组,其长度等于 path 指定文件的字节数。数组内容即文件内容,等价于包含文件内容的字符串字面量。
与 @import 一样,path 可以是绝对路径,也可以相对于当前文件。
另见:
@enumFromInt
@enumFromInt(integer: anytype) anytype
已弃用。请改用 @fromBackingInt 或 @bitCast。
将整数转换为 enum 值,返回类型为推导出的结果类型。
尝试转换枚举中没有对应值的整数,会引发带安全检查的非法行为。注意,非穷尽枚举的整数标记类型中,每个整数都有对应值;_ 表示标记类型中其余全部未命名整数。
另见:
@errorFromInt
@errorFromInt(value: @Int(.unsigned, @bitSizeOf(anyerror))) anyerror
将错误的整数表示转换为全局错误集合类型。
通常建议避免此转换,因为错误的整数表示在源码变化后并不稳定。
尝试转换不对应任何错误的整数,会引发带安全检查的非法行为。
另见:
@errorName
@errorName(err: anyerror) [:0]const u8
返回错误的字符串表示。error.OutOfMem 的字符串表示为 "OutOfMem"。
如果整个应用没有调用 @errorName,或者所有调用的 err 都在编译时已知,则不生成错误名称表。
@errorReturnTrace
@errorReturnTrace() ?*std.lang.StackTrace
如果二进制启用了错误返回追踪,且调用此函数的函数会调用返回错误或错误联合的函数,则返回一个栈追踪对象;否则返回 null。
@errorCast
@errorCast(value: anytype) anytype
将错误集合或错误联合值从一种错误集合转换为另一种。返回类型为推导出的结果类型。尝试转换不属于目标错误集合的错误,会引发带安全检查的非法行为。
@export
@export(comptime ptr: *const anyopaque, comptime options: std.lang.ExportOptions) void
在输出目标文件中创建一个引用 ptr 目标的符号。
ptr 必须指向全局变量或编译时已知常量。
可从 comptime 块调用此内置函数,以有条件地导出符号。当 ptr 指向使用 C 调用约定的函数,且 options.linkage 为 .strong 时,它等价于函数上的 export 关键字:
comptime {
@export(&internalName, .{ .name = "foo", .linkage = .strong });
}
fn internalName() callconv(.c) void {}$ zig build-obj export_builtin.zig
这等价于:
export fn foo() void {}$ zig build-obj export_builtin_equivalent_code.zig
注意,即使使用 export,也可以通过标识符的 @"foo" 语法,为符号名选择任意字符串:
export fn @"A function name that is a complete sentence."() void {}$ zig build-obj export_any_symbol_name.zig
查看生成的目标文件,可以看到符号原样使用了该名称:
00000000000001f0 T A function name that is a complete sentence.
另见:
@extern
@extern(T: type, comptime options: std.lang.ExternOptions) T
在输出目标文件中创建外部符号的引用。T 必须是指针类型。
另见:
@field
@field(lhs: anytype, comptime field_name: []const u8) (field)
通过编译时字符串访问字段,既支持字段,也支持声明。
const std = @import("std");
const expectEqual = std.testing.expectEqual;
const Point = struct {
x: u32,
y: u32,
pub var z: u32 = 1;
};
test "field access by string" {
var p = Point{ .x = 0, .y = 0 };
@field(p, "x") = 4;
@field(p, "y") = @field(p, "x") + 1;
try expectEqual(4, @field(p, "x"));
try expectEqual(5, @field(p, "y"));
}
test "decl access by string" {
try expectEqual(1, @field(Point, "z"));
@field(Point, "z") = 2;
try expectEqual(2, @field(Point, "z"));
}$ zig test test_field_builtin.zig
1/2 test_field_builtin.test.field access by string...OK
2/2 test_field_builtin.test.decl access by string...OK
All 2 tests passed.
@fieldParentPtr
@fieldParentPtr(comptime field_name: []const u8, field_ptr: *T) anytype
给定指向结构体或联合字段的指针,返回指向包含该字段的结构体或联合的指针。返回类型,即指向该父结构体或联合的指针类型,由结果类型推导。
如果 field_ptr 不指向结果类型实例的 field_name 字段,而且结果类型的布局未明确定义,就会引发不进行检查的非法行为。
@FieldType
@FieldType(comptime Type: type, comptime field_name: []const u8) type
给定类型及其一个字段的名称,返回该字段的类型。
@floatCast
@floatCast(value: anytype) anytype
在不同浮点类型之间转换。这种转换安全,但可能损失数值精度。返回类型为推导出的结果类型。
@floatFromInt
@floatFromInt(int: anytype) anytype
将整数转换为最接近的浮点表示,返回类型为推导出的结果类型。反向转换请使用 @round、@floor、@ceil 或 @trunc。此操作对所有整数类型的全部值都合法。
@frameAddress
@frameAddress() usize
返回当前栈帧的基址指针。
其具体含义依赖目标平台,各平台不完全一致。发布模式下,激进优化可能导致无法获得帧地址。
此函数仅在函数作用域内有效。
@fromBackingInt
@fromBackingInt(backing_int: BackingInt(T)) T
将整数转换为 enum、packed struct 或 packed union 值,返回类型为推导出的结果类型。
尝试将不存在对应标记值的整数转换为 enum,会引发带安全检查的非法行为。注意,非穷尽枚举的整数标记类型中,每个整数都有对应值;_ 表示标记类型中其余全部未命名整数。
另见:
@hasDecl
@hasDecl(comptime Namespace: type, comptime name: []const u8) bool
返回命名空间是否具有与 name 匹配的公开声明。
const std = @import("std");
const expect = std.testing.expect;
const Foo = struct {
nope: i32,
pub var blah = "xxx";
const hi = 1;
};
test "@hasDecl" {
try expect(@hasDecl(Foo, "blah"));
// 对于私有声明,@hasDecl 返回 false。
try expect(!@hasDecl(Foo, "hi"));
// @hasDecl 检查声明,而不是字段。
try expect(!@hasDecl(Foo, "nope"));
try expect(!@hasDecl(Foo, "nope1234"));
}$ zig test test_hasDecl_builtin.zig
1/1 test_hasDecl_builtin.test.@hasDecl...OK
All 1 tests passed.
注意:使用 @hasDecl 根据接口是否包含某个声明来实现条件编译,可能在无意中向代码库引入死代码。例如,如果字段被重命名,使用 @hasDecl 的代码仍会成功编译,却没有按预期启用或禁用相应代码块。即使传给 @hasDecl 的字段名称只是拼写错误,编译器也不会察觉。因此,条件允许时,应使用其他方式检查特定声明是否存在。例如,若目标操作系统足以说明某函数是否可用,检查 @import("builtin").target.os.tag 比检查 @hasDecl 更易维护。
另见:
@hasField
@hasField(comptime T: type, comptime name: []const u8) bool
返回结构体、联合或枚举中是否存在指定字段名称。
结果是编译时常量。
不包含函数、变量或常量。
另见:
@import
@import(comptime target: []const u8) anytype
导入 target 处的文件;如果尚未纳入编译,则将其加入。target 可以是相对于包含 @import 调用的文件的另一个文件路径,也可以是模块名称,此时导入该模块的根源文件。无论哪种方式,文件路径都必须以 .zig(Zig 源文件)或 .zon(ZON 数据文件)结尾。
如果 target 指向 Zig 源文件,@import 返回该文件对应的结构体类型,基本上相当于将此内置调用替换为 struct { FILE_CONTENTS }。返回类型为 type。
如果 target 指向 ZON 文件,@import 返回文件中字面量的值。若存在推导出的结果类型,则返回该类型,并将 ZON 字面量解释为该类型;结果类型会在 ZON 表达式中传播。否则,返回类型与对应 Zig 表达式相同,基本上相当于用 ZON 文件内容替换该内置调用。
以下模块始终可供导入:
@import("std")—— Zig 标准库@import("builtin")—— 目标平台特定信息。命令zig build-exe --show-builtin将源码输出至标准输出,以供参考。@import("root")—— 根模块的别名。在典型项目结构中,指回src/main.zig。
另见:
@inComptime
@inComptime() bool
返回此内置函数是否在 comptime 上下文中执行。结果为编译时常量。
可据此提供适用于编译时的替代函数实现,但不应利用它阻止某些函数在编译时求值。
另见:
@intCast
@intCast(int: anytype) anytype
将整数转换为另一种整数类型,同时保持数值不变。返回类型为推导出的结果类型。转换超出目标类型范围的数值,会引发带安全检查的非法行为。
test "integer cast panic" {
var a: u16 = 0xabcd; // 运行时已知
_ = &a;
const b: u8 = @intCast(a);
_ = b;
}$ zig test test_intCast_builtin.zig
1/1 test_intCast_builtin.test.integer cast panic...thread 707070 panic: integer does not fit in destination type
/home/andy/src/zig/doc/langref/test_intCast_builtin.zig:4:19: 0x124c590 in test.integer cast panic (test_intCast_builtin.zig)
const b: u8 = @intCast(a);
^
/home/andy/src/zig/lib/compiler/test_runner.zig:295:25: 0x1200951 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/andy/src/zig/lib/compiler/test_runner.zig:74:28: 0x1200132 in main (test_runner.zig)
return mainTerminal(init);
^
/home/andy/src/zig/lib/std/start.zig:789:88: 0x11fc8cf in callMain (std.zig)
if (fn_info.param_types[0].? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/andy/src/zig/lib/std/start.zig:248:5: 0x11fc2b1 in _start (std.zig)
asm volatile (switch (native_arch) {
^
error: the following test command terminated with signal ABRT:
/home/andy/src/zig/.zig-cache/o/d8b6bb7b92f74a8ddeaad0d5d4b8c5d5/test --seed=0x4df6f8f7
若要截去超出目标类型范围的有效位,使用 @truncate。
如果 T 为 comptime_int,则语义等价于类型强制转换。
@intFromBool
@intFromBool(value: bool) u1
将 true 转为 @as(u1, 1),将 false 转为 @as(u1, 0)。
@intFromEnum
@intFromEnum(enum_or_tagged_union: anytype) anytype
已弃用。请改用 @backingInt 或 @bitCast。
将枚举值转换为其整数标记类型。如果传入标记联合,则使用其标记值作为枚举值。
另见:
@intFromError
@intFromError(err: anytype) @Int(.unsigned, @bitSizeOf(anyerror))
支持以下类型:
将错误转换为该错误的整数表示。
通常建议避免此转换,因为错误的整数表示在源码变化后并不稳定。
另见:
@intFromFloat
@intFromFloat(float: anytype) anytype
已弃用,等价于 @trunc。
另见:
@intFromPtr
@intFromPtr(value: anytype) usize
将 value 转换为表示指针地址的 usize。value 可以是 *T 或 ?*T。
另见:
@max
@max(...) T
接受两个或更多参数,返回其中最大的值。此内置函数接受整数、浮点数及这两类元素的向量。向量情况下按元素执行。
NaN 的处理规则:返回最大的非 NaN 值;如果全部操作数均为 NaN,则返回 NaN。
另见:
@memcpy
@memcpy(noalias dest, noalias source) void
将一个内存区域的字节复制到另一个内存区域。
dest 必须是可变切片、指向数组的可变指针或可变多项指针。其对齐要求和元素类型可以任意。
source 必须是切片、数组指针或多项指针。其对齐要求和元素类型可以任意。
source 的元素类型必须与 dest 的元素类型具有相同内存表示。
与 for 循环类似,source 和 dest 中至少一个必须提供长度;两者都提供长度时,长度必须相同。
最后,两个内存区域不得重叠。
@memset
@memset(dest, elem) void
将内存区域的全部元素设置为 elem。
dest 必须是可变切片或指向数组的可变指针。其对齐要求和元素类型可以任意。
elem 会强制转换为 dest 的元素类型。
若要安全地清零内存中的敏感内容,应使用 std.crypto.secureZero
@memmove
@memmove(dest, source) void
将一个内存区域的字节复制到另一个内存区域;与 @memcpy 不同,允许两个区域重叠。
dest 必须是可变切片、指向数组的可变指针或可变多项指针。其对齐要求和元素类型可以任意。
source 必须是切片、数组指针或多项指针。其对齐要求和元素类型可以任意。
source 的元素类型必须与 dest 的元素类型具有相同内存表示。
与 for 循环类似,source 和 dest 中至少一个必须提供长度;两者都提供长度时,长度必须相同。
@min
@min(...) T
接受两个或更多参数,返回其中最小的值。此内置函数接受整数、浮点数及这两类元素的向量。向量情况下按元素执行。
NaN 的处理规则:返回最小的非 NaN 值;如果全部操作数均为 NaN,则返回 NaN。
另见:
@wasmMemorySize
@wasmMemorySize(index: u32) usize
返回 index 标识的 Wasm 内存大小,以无符号 Wasm 页数表示。注意,每个 Wasm 页大小为 64KB。
这是没有安全机制的底层内建操作,通常供面向 Wasm 的分配器设计者使用。因此,除非从头编写新分配器,否则应使用 @import("std").heap.WasmPageAllocator 等工具。
另见:
@wasmMemoryGrow
@wasmMemoryGrow(index: u32, delta: usize) isize
将 index 标识的 Wasm 内存增大 delta 个 Wasm 页,页数为无符号数。注意,每页大小为 64KB。成功时返回此前内存大小;分配失败时返回 -1。
这是没有安全机制的底层内建操作,通常供面向 Wasm 的分配器设计者使用。因此,除非从头编写新分配器,否则应使用 @import("std").heap.WasmPageAllocator 等工具。
const std = @import("std");
const native_arch = @import("builtin").target.cpu.arch;
const expectEqual = std.testing.expectEqual;
test "@wasmMemoryGrow" {
if (native_arch != .wasm32) return error.SkipZigTest;
const prev = @wasmMemorySize(0);
try expectEqual(@wasmMemoryGrow(0, 1), prev);
try expectEqual(@wasmMemorySize(0), prev + 1);
}$ zig test test_wasmMemoryGrow_builtin.zig
1/1 test_wasmMemoryGrow_builtin.test.@wasmMemoryGrow...SKIP
0 passed; 1 skipped; 0 failed.
另见:
@mod
@mod(numerator: T, denominator: T) T
模除法。对于无符号整数,与 numerator % denominator 相同。调用者保证 denominator != 0,否则启用运行时安全检查时会触发取余除数为零。
@mod(-5, 3) == 1(@divFloor(a, b) * b) + @mod(a, b) == a
如需返回错误码的函数,参见 @import("std").math.mod。
另见:
@mulWithOverflow
@mulWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
执行 a * b,返回包含运算结果和可能的溢出位的元组。
@panic
@panic(message: []const u8) noreturn
调用 panic 处理函数。默认处理器调用根源文件公开的 panic 函数;若未指定,则调用 std/lang.zig 中的 std.lang.default_panic 函数。
通常更适合使用 @import("std").debug.panic。不过,@panic 在以下两种情况下可能有用:
- 从库代码调用程序员在根源文件中公开的自定义 panic 函数。
- 混用 C 和 Zig 代码时,从多个 .o 文件调用同一份规范的 panic 实现。
另见:
@popCount
@popCount(operand: anytype) anytype
@TypeOf(operand) 必须是整数类型。
统计整数中置一的位数,即“人口计数”。
返回类型是无符号整数或无符号整数向量,使用足以表示该整数类型位数的最少位数。
另见:
@prefetch
@prefetch(ptr: anytype, comptime options: PrefetchOptions) void
若目标 CPU 支持,则告知编译器生成预取指令。目标 CPU 不支持所请求的预取指令时,此内置函数不执行操作。它仅影响性能特征,不影响程序行为。
ptr 参数可以是任意指针类型,用于确定要预取的内存地址。函数不会解引用该指针,因此传入指向无效内存的指针完全合法,不会导致非法行为。
可通过 @import("std").lang.PrefetchOptions 找到 PrefetchOptions。
@ptrCast
@ptrCast(value: anytype) anytype
将一种类型的指针转换为另一种类型的指针,返回类型为推导出的结果类型。
允许传入可选指针。将值为 null 的可选指针转换为非可选指针,会引发带安全检查的非法行为。
@ptrCast 不能用于以下操作:
- 移除
const限定符,应使用 @constCast。 - 移除
volatile限定符,应使用 @volatileCast。 - 改变指针地址空间,应使用 @addrSpaceCast。
- 增大指针对齐值,应使用 @alignCast。
- 将非切片指针转换为切片,应使用切片语法
ptr[start..end]。
@ptrFromInt
@ptrFromInt(address: usize) anytype
将整数转换为指针,返回类型为推导出的结果类型。反向转换使用 @intFromPtr。将零地址转换为既非可选、又没有 allowzero 属性的目标类型,在启用运行时安全检查时会触发指针转换产生无效空值的 panic。
如果目标指针类型不允许零地址,而 address 为 0,就会引发带安全检查的非法行为。
另见:
@rem
@rem(numerator: T, denominator: T) T
余数除法。对于无符号整数,与 numerator % denominator 相同。调用者保证 denominator != 0,否则启用运行时安全检查时会触发取余除数为零。
@rem(-5, 3) == -2(@divTrunc(a, b) * b) + @rem(a, b) == a
如需返回错误码的函数,参见 @import("std").math.rem。
另见:
@returnAddress
@returnAddress() usize
返回当前函数返回后将执行的下一条机器码指令地址。
其具体含义依赖目标平台,各平台不完全一致。
此函数仅在函数作用域内有效。如果当前函数内联到调用者,返回地址将针对调用者函数。
@select
@select(comptime T: type, pred: @Vector(len, bool), a: @Vector(len, T), b: @Vector(len, T)) @Vector(len, T)
根据 pred,逐元素从 a 或 b 中选择值。如果 pred[i] 为 true,结果中对应元素为 a[i],否则为 b[i]。
另见:
@setEvalBranchQuota
@setEvalBranchQuota(comptime new_quota: u32) void
增加编译期代码执行允许经过的最大后向分支数,超过此数量后将停止并产生编译错误。
如果 new_quota 小于默认配额 1000,或小于此前显式设置的配额,则忽略。
示例:
test "foo" {
comptime {
var i = 0;
while (i < 1001) : (i += 1) {}
}
}$ zig test test_without_setEvalBranchQuota_builtin.zig
/home/andy/src/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: error: evaluation exceeded 1000 backwards branches
while (i < 1001) : (i += 1) {}
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/andy/src/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: note: use @setEvalBranchQuota() to raise the branch limit from 1000
现在使用 @setEvalBranchQuota:
test "foo" {
comptime {
@setEvalBranchQuota(1001);
var i = 0;
while (i < 1001) : (i += 1) {}
}
}$ zig test test_setEvalBranchQuota_builtin.zig
1/1 test_setEvalBranchQuota_builtin.test.foo...OK
All 1 tests passed.
另见:
@setFloatMode
@setFloatMode(comptime mode: FloatMode) void
更改当前作用域内浮点运算的定义规则。
.strict(默认)—— 浮点运算严格遵循 IEEE 规范。.optimized—— 浮点运算可以执行以下全部操作:- 假设参数和结果均不是 NaN。优化仍须保证处理 NaN 时行为合法,但结果值未定义。
- 假设参数和结果均不是正负无穷。优化仍须保证处理正负无穷时行为合法,但结果值未定义。
- 忽略为零的参数或结果的符号。
- 使用参数的倒数代替除法。
- 执行浮点收缩,例如将乘法后紧接的加法融合为一次融合乘加。
- 执行代数等价但可能改变浮点结果的变换,例如重新结合运算。
-ffast-math。
子作用域会继承浮点模式;任意作用域都可以覆盖。使用 comptime 块可在结构体或模块作用域设置浮点模式。
可通过 @import("std").lang.FloatMode 找到 FloatMode。
另见:
@setRuntimeSafety
@setRuntimeSafety(comptime safety_on: bool) void
设置是否为包含此调用的作用域启用运行时安全检查。
test "@setRuntimeSafety" {
// 此内置函数作用于调用它的作用域。因此,下面的整数溢出
// 在 ReleaseFast 和 ReleaseSmall 模式下不会被捕获:
// var x: u8 = 255;
// x += 1; // ReleaseFast/ReleaseSmall 模式下未检查的非法行为。
{
// 但此块启用了安全检查,因此这里会执行安全检查,
// 即使在 ReleaseFast 和 ReleaseSmall 模式下也是如此。
@setRuntimeSafety(true);
var x: u8 = 255;
x += 1;
{
// 任意作用域都可以覆盖此设置。因此,下面的整数溢出
// 在任何构建模式下都不会被捕获。
@setRuntimeSafety(false);
// var x: u8 = 255;
// x += 1; // 所有构建模式下都未检查的非法行为。
}
}
}$ zig test test_setRuntimeSafety_builtin.zig -Ofast
1/1 test_setRuntimeSafety_builtin.test.@setRuntimeSafety...thread 708729 panic: integer overflow
/home/andy/src/zig/.zig-cache/tmp/13225f94265cb3b9/../../../doc/langref/test_setRuntimeSafety_builtin.zig:11:11: 0x108f638 in test.@setRuntimeSafety (test)
x += 1;
^
/home/andy/src/zig/lib/compiler/test_runner.zig:295:25: 0x107ab92 in mainTerminal (test)
if (test_fn.func()) |_| {
^
/home/andy/src/zig/lib/std/start.zig:789:88: 0x10789c2 in callMain (test)
if (fn_info.param_types[0].? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/andy/src/zig/lib/std/start.zig:248:5: 0x107845d in _start (test)
asm volatile (switch (native_arch) {
^
error: the following test command terminated with signal ABRT:
/home/andy/src/zig/.zig-cache/o/dc0a22baa2769813928145b20c462262/test --seed=0xa6cd7537
注意:计划以 @optimizeFor 替换 @setRuntimeSafety
@shlExact
@shlExact(value: T, shift_amt: Log2T) T
执行左移操作 <<。对于无符号整数,如果任何值为 1 的位被移出,结果未定义;对于有符号整数,如果移出的位与结果符号位不同,结果未定义。
shift_amt 的类型是 log2(@typeInfo(T).int.bits) 位无符号整数,因为 shift_amt >= @typeInfo(T).int.bits 会触发带安全检查的非法行为。
comptime_int 建模为具有无限位数的整数,因此此时 @shlExact 始终能够产生结果,不会产生编译错误。
另见:
@shlWithOverflow
@shlWithOverflow(a: anytype, shift_amt: Log2T) struct { @TypeOf(a), u1 }
执行 a << b,返回包含运算结果和可能的溢出位的元组。
shift_amt 的类型是 log2(@typeInfo(@TypeOf(a)).int.bits) 位无符号整数,因为 shift_amt >= @typeInfo(@TypeOf(a)).int.bits 会触发带安全检查的非法行为。
另见:
@shrExact
@shrExact(value: T, shift_amt: Log2T) T
执行右移操作 >>。调用者保证不会移出任何值为 1 的位。
shift_amt 的类型是 log2(@typeInfo(T).int.bits) 位无符号整数,因为 shift_amt >= @typeInfo(T).int.bits 会触发带安全检查的非法行为。
另见:
@shuffle
@shuffle(comptime E: type, a: @Vector(a_len, E), b: @Vector(b_len, E), comptime mask: @Vector(mask_len, i32)) @Vector(mask_len, E)
根据 mask 从 a 和 b 中选择元素,构造新的向量。
mask 的每个元素从 a 或 b 中选择一个元素。非负数从 a 选择,索引从 0 开始;负数从 b 选择,索引从 -1 开始递减。建议对 b 的索引使用 ~ 运算符,使两组索引都从 0 开始,即 ~@as(i32, 0) 等于 -1。
对于 mask 的每个元素,如果该元素或从 a、b 中选中的值为 undefined,则结果元素为 undefined。
a_len 与 b_len 的长度可以不同。mask 中出现越界元素索引会产生编译错误。
如果 a 或 b 为 undefined,则等价于长度与另一个向量相同、元素全为 undefined 的向量。两者都为 undefined 时,@shuffle 返回元素全为 undefined 的向量。
E 必须是整数、浮点数、指针或 bool。掩码向量长度可以任意,并决定结果长度。
const std = @import("std");
const expectEqualStrings = std.testing.expectEqualStrings;
test "vector @shuffle" {
const a = @Vector(7, u8){ 'o', 'l', 'h', 'e', 'r', 'z', 'w' };
const b = @Vector(4, u8){ 'w', 'd', '!', 'x' };
// 若只在单个向量内重排,第二个参数传入 undefined。
// 注意,可以重排、复制或省略输入向量中的元素
const mask1 = @Vector(5, i32){ 2, 3, 1, 1, 0 };
const res1: @Vector(5, u8) = @shuffle(u8, a, undefined, mask1);
try expectEqualStrings("hello", &@as([5]u8, res1));
// 合并两个向量
const mask2 = @Vector(6, i32){ -1, 0, 4, 1, -2, -3 };
const res2: @Vector(6, u8) = @shuffle(u8, a, b, mask2);
try expectEqualStrings("world!", &@as([6]u8, res2));
}$ zig test test_shuffle_builtin.zig
1/1 test_shuffle_builtin.test.vector @shuffle...OK
All 1 tests passed.
另见:
@sizeOf
@sizeOf(comptime T: type) comptime_int
返回在内存中存储 T 所需的字节数。结果是依赖目标平台的编译时常量。
此大小可能包含填充字节。如果内存中有两个连续的 T,大小就等于索引 0 处元素与索引 1 处元素之间的字节偏移。对于整数,应考虑需要的是 @sizeOf(T) 还是 @typeInfo(T).int.bits。
此函数衡量运行时大小。对于 comptime_int、type 等不允许在运行时使用的类型,结果为 0。
另见:
@splat
@splat(element: anytype) anytype
生成每个元素都等于 element 的数组或向量。返回类型及元素数量均由结果类型推导。
const std = @import("std");
const expectEqualSlices = std.testing.expectEqualSlices;
test "vector @splat" {
const scalar: u32 = 5;
const result: @Vector(4, u32) = @splat(scalar);
try expectEqualSlices(u32, &[_]u32{ 5, 5, 5, 5 }, &@as([4]u32, result));
}
test "array @splat" {
const scalar: u32 = 5;
const result: [4]u32 = @splat(scalar);
try expectEqualSlices(u32, &[_]u32{ 5, 5, 5, 5 }, &@as([4]u32, result));
}$ zig test test_splat_builtin.zig
1/2 test_splat_builtin.test.vector @splat...OK
2/2 test_splat_builtin.test.array @splat...OK
All 2 tests passed.
另见:
@reduce
@reduce(comptime op: std.lang.ReduceOp, value: anytype) E
使用指定运算符 op 对向量元素执行顺序水平归约,将其转换为 E 类型的标量值。
并非每种向量元素类型都支持所有运算符:
注意,整数类型的 .Add 和 .Mul 归约采用回绕语义;对浮点类型,除非浮点模式设为 .optimized,否则会保留运算结合顺序。
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "vector @reduce" {
const V = @Vector(4, i32);
const value = V{ 1, -1, 1, -1 };
const result = value > @as(V, @splat(0));
// 结果为 { true, false, true, false };
try comptime expectEqual(@Vector(4, bool), @TypeOf(result));
const is_all_true = @reduce(.And, result);
try comptime expectEqual(bool, @TypeOf(is_all_true));
try expectEqual(false, is_all_true);
}$ zig test test_reduce_builtin.zig
1/1 test_reduce_builtin.test.vector @reduce...OK
All 1 tests passed.
另见:
@src
@src() std.lang.SourceLocation
返回表示函数名称及源码位置的 SourceLocation 结构体。必须在函数中调用。
const std = @import("std");
const expect = std.testing.expect;
const expectEqual = std.testing.expectEqual;
test "@src" {
try doTheTest();
}
fn doTheTest() !void {
const src = @src();
try expectEqual(10, src.line);
try expectEqual(17, src.column);
try expect(std.mem.endsWith(u8, src.fn_name, "doTheTest"));
try expect(std.mem.endsWith(u8, src.file, "test_src_builtin.zig"));
}$ zig test test_src_builtin.zig
1/1 test_src_builtin.test.@src...OK
All 1 tests passed.
@sqrt
@sqrt(value: anytype) @TypeOf(value)
计算浮点数的平方根,存在专用硬件指令时使用该指令。
@sin
@sin(value: anytype) @TypeOf(value)
计算以弧度表示的浮点数的正弦,存在专用硬件指令时使用该指令。
@cos
@cos(value: anytype) @TypeOf(value)
计算以弧度表示的浮点数的余弦,存在专用硬件指令时使用该指令。
@tan
@tan(value: anytype) @TypeOf(value)
计算以弧度表示的浮点数的正切,存在专用硬件指令时使用该指令。
@exp
@exp(value: anytype) @TypeOf(value)
计算以 e 为底的浮点指数函数,存在专用硬件指令时使用该指令。
@exp2
@exp2(value: anytype) @TypeOf(value)
计算以 2 为底的浮点指数函数,存在专用硬件指令时使用该指令。
@log
@log(value: anytype) @TypeOf(value)
返回浮点数的自然对数,存在专用硬件指令时使用该指令。
@log2
@log2(value: anytype) @TypeOf(value)
返回浮点数以 2 为底的对数,存在专用硬件指令时使用该指令。
@log10
@log10(value: anytype) @TypeOf(value)
返回浮点数以 10 为底的对数,存在专用硬件指令时使用该指令。
@abs
@abs(value: anytype) anytype
返回整数或浮点数的绝对值,存在专用硬件指令时使用该指令。操作数为整数时,返回类型始终是与操作数等位宽的无符号整数。支持无符号整数操作数。对于有符号整数,此内置函数不会溢出。
@floor
@floor(value: anytype) @TypeOf(value)
返回不大于给定浮点数的最大整数值,存在专用硬件指令时使用该指令。
推导出的结果类型为整数时,从向下取整后的结果提取整数部分。该值无法容纳于目标类型时,会引发带安全检查的非法行为。
@ceil
@ceil(value: anytype) @TypeOf(value)
返回不小于给定浮点数的最小整数值,存在专用硬件指令时使用该指令。
推导出的结果类型为整数时,从向上取整后的结果提取整数部分。该值无法容纳于目标类型时,会引发带安全检查的非法行为。
@trunc
@trunc(value: anytype) @TypeOf(value)
将给定浮点数朝零舍入为整数值,存在专用硬件指令时使用该指令。
推导出的结果类型为整数时,从截断后的结果提取整数部分。该值无法容纳于目标类型时,会引发带安全检查的非法行为。
@round
@round(value: anytype) @TypeOf(value)
将给定浮点数舍入到最近整数;与两个整数距离相同时,朝远离零的方向舍入。存在专用硬件指令时使用该指令。
const expectEqual = @import("std").testing.expectEqual;
test "@round" {
try expectEqual(1, @round(1.4));
try expectEqual(2, @round(1.5));
try expectEqual(-1, @round(-1.4));
try expectEqual(-3, @round(-2.5));
}$ zig test test_round_builtin.zig
1/1 test_round_builtin.test.@round...OK
All 1 tests passed.
推导出的结果类型为整数时,从舍入后的结果提取整数部分。该值无法容纳于目标类型时,会引发带安全检查的非法行为。
@subWithOverflow
@subWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
执行 a - b,返回包含运算结果和可能的溢出位的元组。
@tagName
@tagName(value: anytype) [:0]const u8
将枚举值或联合值转换为表示其名称的字符串字面量。
如果枚举为非穷尽枚举,且标记值没有对应名称,则引发带安全检查的非法行为。
@This
@This() type
返回包含此调用的最内层结构体、枚举或联合。对于需要引用自身的匿名结构体,这很有用:
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "@This()" {
var items = [_]i32{ 1, 2, 3, 4 };
const list = List(i32){ .items = items[0..] };
try expectEqual(4, list.length());
}
fn List(comptime T: type) type {
return struct {
const Self = @This();
items: []T,
fn length(self: Self) usize {
return self.items.len;
}
};
}$ zig test test_this_builtin.zig
1/1 test_this_builtin.test.@This()...OK
All 1 tests passed.
在文件作用域使用 @This() 时,返回当前文件对应结构体的引用。
@trap
@trap() noreturn
插入平台相关的陷阱或停机指令,用于异常终止程序。实现方式可能是显式生成一条无效指令,引发某种非法指令异常。与 @breakpoint() 不同,执行不会越过此位置继续。
在函数作用域之外使用此内置函数会产生编译错误。
另见:
@truncate
@truncate(integer: anytype) anytype
截断整数类型的位,得到较小或相同大小的整数类型。返回类型为推导出的结果类型。
无论目标平台的字节序如何,始终截断整数的高有效位。
即使数值超出目标类型范围,调用 @truncate 也具有明确定义,代码可以正常工作:
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "integer truncation" {
const a: u16 = 0xabcd;
const b: u8 = @truncate(a);
try expectEqual(0xcd, b);
}$ zig test test_truncate_builtin.zig
1/1 test_truncate_builtin.test.integer truncation...OK
All 1 tests passed.
对于保证能够容纳于目标类型的数值转换,使用 @intCast。
@EnumLiteral
@EnumLiteral() type
返回仅限编译时使用的“枚举字面量”类型,即尚未强制转换的枚举字面量的类型。此类型的值可以强制转换为包含匹配字段的任意 enum。
@Int
@Int(comptime signedness: std.lang.Signedness, comptime bits: u16) type
返回具有指定符号性和位宽的整数类型。
例如,@Int(.unsigned, 18) 返回类型 u18。
@Tuple
@Tuple(comptime field_types: []const type) type
返回具有指定字段类型的元组类型。
@Pointer
@Pointer(
comptime size: std.lang.Type.Pointer.Size,
comptime attrs: std.lang.Type.Pointer.Attributes,
comptime Element: type,
comptime sentinel: ?Element,
) type
返回属性由参数指定的指针类型。
@Fn
@Fn(
comptime param_types: []const type,
comptime param_attrs: *const [param_types.len]std.lang.Type.Fn.ParamAttributes,
comptime ReturnType: type,
comptime attrs: std.lang.Type.Fn.Attributes,
) type
返回属性由参数指定的函数类型。
@Struct
@Struct(
comptime layout: std.lang.Type.ContainerLayout,
comptime BackingInt: ?type,
comptime field_names: []const []const u8,
comptime field_types: *const [field_names.len]type,
comptime field_attrs: *const [field_names.len]std.lang.Type.Struct.FieldAttributes,
) type
返回属性由参数指定的 struct 类型。
@Union
@Union(
comptime layout: std.lang.Type.ContainerLayout,
/// 根据 `layout`,表示枚举标记类型或底层整数类型。
comptime ArgType: ?type,
comptime field_names: []const []const u8,
comptime field_types: *const [field_names.len]type,
comptime field_attrs: *const [field_names.len]std.lang.Type.Union.FieldAttributes,
) type
返回属性由参数指定的 union 类型。
@Enum
@Enum(
comptime TagInt: type,
comptime mode: std.lang.Type.Enum.Mode,
comptime field_names: []const []const u8,
comptime field_values: *const [field_names.len]TagInt,
) type
返回属性由参数指定的 enum 类型。
@SpirvType
@SpirvType(comptime options: std.lang.Type.Spirv) type
返回属性由参数指定的 SPIR-V 类型。
| 标记 | SPIR-V 对应类型 | 说明 |
|---|---|---|
.sampler |
OpTypeSampler |
不透明采样器 |
.image |
OpTypeImage |
不透明图像 |
.sampled_image |
OpTypeSampledImage |
与采样器组合的不透明图像 |
.runtime_array |
OpTypeRuntimeArray |
长度在运行时确定的数组。结果类型支持索引,并公开 .len 字段。它只能作为 extern struct 的最后一个字段。 |
@typeInfo
@typeInfo(comptime T: type) std.lang.Type
提供类型反射。
结构体、联合、枚举和错误集合的类型信息包含字段,并保证字段顺序与源文件中的出现顺序一致。
结构体、联合、枚举和不透明类型的类型信息包含声明,也保证声明顺序与源文件中的出现顺序一致。
@typeName
@typeName(T: type) *const [N:0]u8
以数组形式返回类型的字符串表示,等价于类型名称的字符串字面量。返回的名称是完全限定名称,以一系列点连接父命名空间并包含在类型名称中。
@TypeOf
@TypeOf(...) type
@TypeOf 是特殊内置函数,接受任意非零数量的表达式参数,并通过同级类型解析返回它们结果的类型。
这些表达式会进行求值,但保证不具有任何运行时副作用:
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "no runtime side effects" {
var data: i32 = 0;
const T = @TypeOf(foo(i32, &data));
try comptime expectEqual(i32, T);
try expectEqual(0, data);
}
fn foo(comptime T: type, ptr: *T) T {
ptr.* += 1;
return ptr.*;
}$ zig test test_TypeOf_builtin.zig
1/1 test_TypeOf_builtin.test.no runtime side effects...OK
All 1 tests passed.
@unionInit
@unionInit(comptime Union: type, comptime active_field_name: []const u8, init_expr) Union
与 union 初始化语法相同,但字段名是编译时已知值,而不是标识符标记。
@unionInit 将其结果位置转发给 init_expr。
@Vector
@Vector(len: comptime_int, Element: type) type
创建向量。
@volatileCast
@volatileCast(value: anytype) DestType
移除指针的 volatile 限定符。
@workGroupId
@workGroupId(comptime dimension: u32) u32
返回当前内核调用中,工作组在 dimension 维度上的索引。
@workGroupSize
@workGroupSize(comptime dimension: u32) u32
返回工作组在 dimension 维度上的工作项数量。
@workItemId
@workItemId(comptime dimension: u32) u32
返回工作项在工作组中 dimension 维度上的索引。返回范围为 0(包含)至 @workGroupSize(dimension)(不包含)。