跳转到内容
语言参考Zig 0.17.1官方原文

内置函数由编译器提供,以 @ 为前缀。参数上的 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 整除的整数类型或整数向量类型。

operand 可以是整数或向量。

交换整数的字节顺序,将大端整数变为小端整数,也将小端整数变为大端整数。

注意,对于与字节序有关的内存布局,整数类型应关联到 @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

调用函数,与在表达式后添加圆括号进行调用相同:

test_call_builtin.zig
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 枚举:

lang.CallModifier struct.zig
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 可以是整数或向量。

计算整数从最高有效位开始连续为零的位数,即“前导零计数”。

返回类型是无符号整数或无符号整数向量,使用足以表示该整数类型位数的最少位数。

如果 operand 为零,@clz 返回整数类型 T 的位宽。

另见:

@cmpxchgStrong

@cmpxchgStrong(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T

执行强原子比较交换操作;当前值等于给定预期值时返回 null。它等价于以下代码,但整个过程为原子操作:

not_atomic_cmpxchgStrong.zig
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。它等价于以下代码,但整个过程为原子操作:

cmpxchgWeakButNotAtomic
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 调试”。

test_compileLog_builtin.zig
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/alexrp/Sources/ziglang/zig/doc/langref/test_compileLog_builtin.zig:5:5: error: found compile log statement
@compileLog("comptime val1 = ", val1);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_compileLog_builtin.zig:11:5: note: also here
@compileLog("comptime in main");
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
referenced by:
test.main: /home/alexrp/Sources/ziglang/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 可以是整数或向量。

计算整数从最低有效位开始连续为零的位数,即“尾随零计数”。

返回类型是无符号整数或无符号整数向量,使用足以表示该整数类型位数的最少位数。

如果 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 关键字:

export_builtin.zig
comptime {
@export(&internalName, .{ .name = "foo", .linkage = .strong });
}
fn internalName() callconv(.c) void {}
命令行
$ zig build-obj export_builtin.zig

这等价于:

export_builtin_equivalent_code.zig
export fn foo() void {}
命令行
$ zig build-obj export_builtin_equivalent_code.zig

注意,即使使用 export,也可以通过标识符的 @"foo" 语法,为符号名选择任意字符串:

export_any_symbol_name.zig
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)

通过编译时字符串访问字段,既支持字段,也支持声明。

test_field_builtin.zig
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 匹配的公开声明。

test_hasDecl_builtin.zig
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_intCast_builtin.zig
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 480502 panic: integer does not fit in destination type
/home/alexrp/Sources/ziglang/zig/doc/langref/test_intCast_builtin.zig:4:19: 0x124e970 in test.integer cast panic (test_intCast_builtin.zig)
const b: u8 = @intCast(a);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/compiler/test_runner.zig:295:25: 0x1202c41 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/compiler/test_runner.zig:74:28: 0x1202422 in main (test_runner.zig)
return mainTerminal(init);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:789:88: 0x11febbf in callMain (std.zig)
if (fn_info.param_types[0].? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11fe5a1 in _start (std.zig)
asm volatile (switch (native_arch) {
^
error: the following test command terminated with signal ABRT:
/home/alexrp/Sources/ziglang/zig/.zig-cache/o/84d307eda13666f1401fe5719873a83f/test --seed=0xeec06f0d

若要截去超出目标类型范围的有效位,使用 @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 等工具。

test_wasmMemoryGrow_builtin.zig
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) 必须是整数类型。

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_without_setEvalBranchQuota_builtin.zig
test "foo" {
comptime {
var i = 0;
while (i < 1001) : (i += 1) {}
}
}
命令行
$ zig test test_without_setEvalBranchQuota_builtin.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: error: evaluation exceeded 1000 backwards branches
while (i < 1001) : (i += 1) {}
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: note: use @setEvalBranchQuota() to raise the branch limit from 1000

现在使用 @setEvalBranchQuota:

test_setEvalBranchQuota_builtin.zig
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 时行为合法,但结果值未定义。
    • 假设参数和结果均不是正负无穷。优化仍须保证处理正负无穷时行为合法,但结果值未定义。
    • 忽略为零的参数或结果的符号。
    • 使用参数的倒数代替除法。
    • 执行浮点收缩,例如将乘法后紧接的加法融合为一次融合乘加。
    • 执行代数等价但可能改变浮点结果的变换,例如重新结合运算。
    这等价于 GCC 中的 -ffast-math。

子作用域会继承浮点模式;任意作用域都可以覆盖。使用 comptime 块可在结构体或模块作用域设置浮点模式。

可通过 @import("std").lang.FloatMode 找到 FloatMode。

另见:

@setRuntimeSafety

@setRuntimeSafety(comptime safety_on: bool) void

设置是否为包含此调用的作用域启用运行时安全检查。

test_setRuntimeSafety_builtin.zig
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 659302 panic: integer overflow
/home/alexrp/Sources/ziglang/zig/.zig-cache/tmp/505a89e47134ccd/../../../doc/langref/test_setRuntimeSafety_builtin.zig:11:11: 0x1090528 in test.@setRuntimeSafety (test)
x += 1;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/compiler/test_runner.zig:295:25: 0x107ba62 in mainTerminal (test)
if (test_fn.func()) |_| {
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:789:88: 0x1079892 in callMain (test)
if (fn_info.param_types[0].? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x107932d in _start (test)
asm volatile (switch (native_arch) {
^
error: the following test command terminated with signal ABRT:
/home/alexrp/Sources/ziglang/zig/.zig-cache/o/0fb35c361b52d8c265962578a2a24653/test --seed=0x7e6fbe56

注意:计划以 @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。掩码向量长度可以任意,并决定结果长度。

test_shuffle_builtin.zig
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 的数组或向量。返回类型及元素数量均由结果类型推导。

test_splat_builtin.zig
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 类型的标量值。

并非每种向量元素类型都支持所有运算符:

  • 整数向量支持全部运算符。
  • bool 向量还支持 .And、.Or、.Xor,
  • 浮点向量还支持 .Min、.Max、.Add、.Mul,

注意,整数类型的 .Add 和 .Mul 归约采用回绕语义;对浮点类型,除非浮点模式设为 .optimized,否则会保留运算结合顺序。

test_reduce_builtin.zig
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 结构体。必须在函数中调用。

test_src_builtin.zig
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)

将给定浮点数舍入到最近整数;与两个整数距离相同时,朝远离零的方向舍入。存在专用硬件指令时使用该指令。

test_round_builtin.zig
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

返回包含此调用的最内层结构体、枚举或联合。对于需要引用自身的匿名结构体,这很有用:

test_this_builtin.zig
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 也具有明确定义,代码可以正常工作:

test_truncate_builtin.zig
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 是特殊内置函数,接受任意非零数量的表达式参数,并通过同级类型解析返回它们结果的类型。

这些表达式会进行求值,但保证不具有任何运行时副作用:

test_TypeOf_builtin.zig
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)(不包含)。