\\ Performs result.* = a + b. If overflow or underflow occurs, stores the overflowed bits in result and returns true. If no overflow or underflow occurs, returns false.
\\ This function returns the number of bytes that this type should be aligned to for the current target to match the C ABI. When the child type of a pointer has this alignment, the alignment can be omitted from the type.
\\```zig
\\const expect = @import("std").testing.expect;
\\comptime {
\\ expect(*u32 == *align(@alignOf(u32)) u32);
\\}
\\```
\\ The result is a target-specific compile time constant. It is guaranteed to be less than or equal to @sizeOf(T).
\\ Performs Type Coercion. This cast is allowed when the conversion is unambiguous and safe, and is the preferred way to convert between types, whenever possible.
\\ @asyncCall performs an async call on a function pointer, which may or may not be an async function.
\\ The provided frame_buffer must be large enough to fit the entire function frame. This size can be determined with @frameSize. To provide a too-small buffer invokes safety-checked Undefined Behavior.
\\ result_ptr is optional (null may be provided). If provided, the function call will write its result directly to the result pointer, which will be available to read after await completes. Any result location provided to await will copy the result from result_ptr.
\\test.zig
\\```zig
\\const std = @import("std");
\\const expect = std.testing.expect;
\\
\\test "async fn pointer in a struct field" {
\\ var data: i32 = 1;
\\ const Foo = struct {
\\ bar: fn (*i32) callconv(.Async) void,
\\ };
\\ var foo = Foo{ .bar = func };
\\ var bytes: [64]u8 align(@alignOf(@Frame(func))) = undefined;
\\ const f = @asyncCall(&bytes, {}, foo.bar, .{&data});
\\ expect(data == 2);
\\ resume f;
\\ expect(data == 4);
\\}
\\
\\fn func(y: *i32) void {
\\ defer y.* += 2;
\\ y.* += 1;
\\ suspend;
\\}
\\```
\\```zig
\\$ zig test test.zig
\\1/1 test "async fn pointer in a struct field"... OK
\\ Returns the bit offset of a field relative to its containing struct.
\\ For non packed structs, this will always be divisible by 8. For packed structs, non-byte-aligned fields will share a byte offset, but they will have different bit offsets.
},
.{
.name="@boolToInt",
.signature="@boolToInt(value: bool) u1",
.snippet="@boolToInt(${1:value: bool})",
.documentation=
\\ Converts true to u1(1) and false to u1(0).
\\ If the value is known at compile-time, the return type is comptime_int instead of u1.
\\T must be an integer type with bit count evenly divisible by 8.
\\operand may be an integer or vector.
\\ Swaps the byte order of the integer. This converts a big endian integer to a little endian integer, and converts a little endian integer to a big endian integer.
\\ Note that for the purposes of memory layout with respect to endianness, the integer type should be related to the number of bytes reported by @sizeOf bytes. This is demonstrated with u24. @sizeOf(u24) == 4, which means that a u24 stored in memory takes 4 bytes, and those 4 bytes are what are swapped on a little vs big endian system. On the other hand, if T is specified to be u24, then only 3 bytes are reversed.
\\ This appends #define $name $value to the @cImport temporary buffer.
\\ To define without a value, like this:
\\```zig
\\#define _GNU_SOURCE
\\```
\\ Use the void value, like this:
\\```zig
\\@cDefine("_GNU_SOURCE", {})
\\```
},
.{
.name="@cImport",
.signature="@cImport(expression) type",
.snippet="@cImport(${1:expression})",
.documentation=
\\ This function parses C code and imports the functions, types, variables, and compatible macro definitions into a new empty struct type, and then returns that type.
\\ expression is interpreted at compile time. The builtin functions @cInclude, @cDefine, and @cUndef work within this expression, appending to a temporary buffer which is then parsed as C code.
\\ Usually you should only have one @cImport in your entire application, because it saves the compiler from invoking clang multiple times, and prevents inline functions from being duplicated.
\\ Reasons for having multiple @cImport expressions would be:
},
.{
.name="@cInclude",
.signature="@cInclude(comptime path: []u8)",
.snippet="@cInclude(${1:comptime path: []u8})",
.documentation=
\\ This function can only occur inside @cImport.
\\ This appends #include <$path>\n to the c_import temporary buffer.
\\ This function counts the number of most-significant (leading in a big-Endian sense) zeroes in integer.
\\ If integer is known at comptime, the return type is comptime_int. Otherwise, the return type is an unsigned integer with the minimum number of bits that can represent the bit count of the integer type.
\\ If integer is zero, @clz returns the bit width of integer type T.
\\ if (old_value == expected_value and usuallyTrueButSometimesFalse()) {
\\ ptr.* = new_value;
\\ return null;
\\ } else {
\\ return old_value;
\\ }
\\}
\\```
\\ If you are using cmpxchg in a loop, the sporadic failure will be no problem, and cmpxchgWeak is the better choice, because it can be implemented more efficiently in machine instructions. However if you need a stronger guarantee, use @cmpxchgStrong.
\\ T must be a pointer, a bool, a float, an integer or an enum.
\\@typeInfo(@TypeOf(ptr)).Pointer.alignment must be >= @sizeOf(T).
\\ This function, when semantically analyzed, causes a compile error with the message msg.
\\ There are several ways that code avoids being semantically checked, such as using if or switch with compile time constants, and comptime functions.
},
.{
.name="@compileLog",
.signature="@compileLog(args: ...)",
.snippet="@compileLog(${1:args: ...})",
.documentation=
\\ This function prints the arguments passed to it at compile-time.
\\ To prevent accidentally leaving compile log statements in a codebase, a compilation error is added to the build, pointing to the compile log statement. This error prevents code from being generated, but does not otherwise interfere with analysis.
\\ This function can be used to do "printf debugging" on compile-time executing code.
\\test.zig
\\```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
\\$ zig test test.zig
\\| *"comptime in main"
\\| *"comptime val1 = ", 99
\\./docgen_tmp/test.zig:11:5: error: found compile log statement
\\ @compileLog("comptime in main");
\\ ^
\\./docgen_tmp/test.zig:1:35: note: referenced here
\\const print = @import("std").debug.print;
\\ ^
\\./docgen_tmp/test.zig:13:5: note: referenced here
\\ print("Runtime in main, num1 = {}.\n", .{num1});
\\ ^
\\./docgen_tmp/test.zig:5:5: error: found compile log statement
\\ @compileLog("comptime val1 = ", val1);
\\ ^
\\./docgen_tmp/test.zig:13:46: note: referenced here
\\ print("Runtime in main, num1 = {}.\n", .{num1});
\\ ^
\\
\\```
\\ will ouput:
\\ If all @compileLog calls are removed or not encountered by analysis, the program compiles successfully and the generated executable prints:
\\test.zig
\\```zig
\\const print = @import("std").debug.print;
\\
\\const num1 = blk: {
\\ var val1: i32 = 99;
\\ val1 = val1 + 1;
\\ break :blk val1;
\\};
\\
\\test "main" {
\\ print("Runtime in main, num1 = {}.\n", .{num1});
\\ This function counts the number of least-significant (trailing in a big-Endian sense) zeroes in integer.
\\ If integer is known at comptime, the return type is comptime_int. Otherwise, the return type is an unsigned integer with the minimum number of bits that can represent the bit count of the integer type.
\\ If integer is zero, @ctz returns the bit width of integer type T.
},
.{
.name="@cUndef",
.signature="@cUndef(comptime name: []u8)",
.snippet="@cUndef(${1:comptime name: []u8})",
.documentation=
\\ This function can only occur inside @cImport.
\\ This appends #undef $name to the @cImport temporary buffer.
\\ Floored division. Rounds toward negative infinity. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeInfo(T) == .Int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
\\ Truncated division. Rounds toward zero. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeInfo(T) == .Int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
\\ This function returns a compile time constant pointer to null-terminated, fixed-size array with length equal to the byte count of the file given by path. The contents of the array are the contents of the file. This is equivalent to a string literal with the file contents.
\\ path is absolute or relative to the current file, just like @import.
\\ This function returns the string representation of an error. The string representation of error.OutOfMem is "OutOfMem".
\\ If there are no calls to @errorName in an entire application, or all calls have a compile-time known value for err, then no error name table will be generated.
\\ If the binary is built with error return tracing, and this function is invoked in a function that calls a function with an error or error union return type, returns a stack trace object. Otherwise returns `null`.
\\ Converts an error value from one error set to another error set. Attempting to convert an error which is not in the destination error set results in safety-protected Undefined Behavior.
\\ This function can be called from a comptime block to conditionally export symbols. When target is a function with the C calling convention and options.linkage is Strong, this is equivalent to the export keyword used on a function:
\\ Converts the integer part of a floating point number to the destination type.
\\ If the integer part of the floating point number cannot fit in the destination type, it invokes safety-checked Undefined Behavior.
},
.{
.name="@frame",
.signature="@frame() *@Frame(func)",
.snippet="@frame()",
.documentation=
\\ This function returns a pointer to the frame for a given function. This type can be coerced to anyframe->T and to anyframe, where T is the return type of the function in scope.
\\ This function does not mark a suspension point, but it does cause the function in scope to become an async function.
},
.{
.name="@Frame",
.signature="@Frame(func: anytype) type",
.snippet="@Frame(${1:func: anytype})",
.documentation=
\\ This function returns the frame type of a function. This works for Async Functions as well as any function without a specific calling convention.
\\ This type is suitable to be used as the return type of async which allows one to, for example, heap-allocate an async function frame:
\\ This function returns the base pointer of the current stack frame.
\\ The implications of this are target specific and not consistent across all platforms. The frame address may not be available in release mode due to aggressive optimizations.
\\ This function is only valid within function scope.
},
.{
.name="@frameSize",
.signature="@frameSize() usize",
.snippet="@frameSize()",
.documentation=
\\ This is the same as @sizeOf(@Frame(func)), where func may be runtime-known.
\\ This function is typically used in conjunction with @asyncCall.
\\Returns whether the field name of a struct, union, or enum exists.
\\ The result is a compile time constant.
\\ It does not include functions, variables, or constants.
},
.{
.name="@import",
.signature="@import(comptime path: []u8) type",
.snippet="@import(${1:comptime path: []u8})",
.documentation=
\\ This function finds a zig file corresponding to path and adds it to the build, if it is not already added.
\\ Zig source files are implicitly structs, with a name equal to the file's basename with the extension truncated. @import returns the struct type corresponding to the file.
\\ Declarations which have the pub keyword may be referenced from a different source file than the one they are declared in.
\\ path can be a relative path or it can be the name of a package. If it is a relative path, it is relative to the file that contains the @import function call.
\\ Converts an integer to another integer while keeping the same numerical value. Attempting to convert a number which is out of range of the destination type results in safety-protected Undefined Behavior.
\\ If T is comptime_int, then this is semantically equivalent to Type Coercion.
\\ This function sets a region of memory to c. dest is a pointer.
\\ This function is a low level intrinsic with no safety mechanisms. Most code should not use this function, instead using something like this:
\\```zig
\\for (dest[0..byte_count]) |*b| b.* = c;
\\```
\\ The optimizer is intelligent enough to turn the above snippet into a memset.
\\There is also a standard library function for this:
\\```zig
\\const mem = @import("std").mem;
\\mem.set(u8, dest, c);
\\```
},
.{
.name="@wasmMemorySize",
.signature="@wasmMemorySize(index: u32) u32",
.snippet="@wasmMemorySize(${1:index: u32})",
.documentation=
\\ This function returns the size of the Wasm memory identified by index as an unsigned value in units of Wasm pages. Note that each Wasm page is 64KB in size.
\\ This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like @import("std").heap.WasmPageAllocator.
\\ This function increases the size of the Wasm memory identified by index by delta in units of unsigned number of Wasm pages. Note that each Wasm page is 64KB in size. On success, returns previous memory size; on failure, if the allocation fails, returns -1.
\\ This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like @import("std").heap.WasmPageAllocator.
\\test.zig
\\```zig
\\const std = @import("std");
\\const builtin = @import("builtin");
\\const expect = std.testing.expect;
\\
\\test "@wasmMemoryGrow" {
\\ if (builtin.arch != .wasm32) return error.SkipZigTest;
\\ Performs result.* = a * b. If overflow or underflow occurs, stores the overflowed bits in result and returns true. If no overflow or underflow occurs, returns false.
\\ Invokes the panic handler function. By default the panic handler function calls the public panic function exposed in the root source file, or if there is not one specified, the std.builtin.default_panic function from std/builtin.zig.
\\Generally it is better to use @import("std").debug.panic. However, @panic can be useful for 2 scenarios:
\\ If integer is known at comptime, the return type is comptime_int. Otherwise, the return type is an unsigned integer with the minimum number of bits that can represent the bit count of the integer type.
\\ Remainder division. For unsigned integers this is the same as numerator % denominator. Caller guarantees denominator > 0.
},
.{
.name="@returnAddress",
.signature="@returnAddress() usize",
.snippet="@returnAddress()",
.documentation=
\\ This function returns the address of the next machine code instruction that will be executed when the current function returns.
\\ The implications of this are target specific and not consistent across all platforms.
\\ This function is only valid within function scope. If the function gets inlined into a calling function, the returned address will apply to the calling function.
\\ Performs result.* = a << b. If overflow or underflow occurs, stores the overflowed bits in result and returns true. If no overflow or underflow occurs, returns false.
\\ The type of shift_amt is an unsigned integer with log2(T.bit_count) bits. This is because shift_amt >= T.bit_count is undefined behavior.
\\ Constructs a new vector by selecting elements from a and b based on mask.
\\ Each element in mask selects an element from either a or b. Positive numbers select from a starting at 0. Negative values select from b, starting at -1 and going down. It is recommended to use the ~ operator from indexes from b so that both indexes can start from 0 (i.e. ~@as(i32, 0) is -1).
\\ For each element of mask, if it or the selected value from a or b is undefined, then the resulting element is undefined.
\\ a_len and b_len may differ in length. Out-of-bounds element indexes in mask result in compile errors.
\\ If a or b is undefined, it is equivalent to a vector of all undefined with the same length as the other vector. If both vectors are undefined, @shuffle returns a vector with all elements undefined.
\\ E must be an integer, float, pointer, or bool. The mask may be any vector length, and its length determines the result length.
\\ This function returns the number of bytes it takes to store T in memory. The result is a target-specific compile time constant.
\\ This size may contain padding bytes. If there were two consecutive T in memory, this would be the offset in bytes between element at index 0 and the element at index 1. For integer, consider whether you want to use @sizeOf(T) or @typeInfo(T).Int.bits.
\\ This function measures the size at runtime. For types that are disallowed at runtime, such as comptime_int and type, the result is 0.
\\ Performs result.* = a - b. If overflow or underflow occurs, stores the overflowed bits in result and returns true. If no overflow or underflow occurs, returns false.
},
.{
.name="@tagName",
.signature="@tagName(value: anytype) []const u8",
.snippet="@tagName(${1:value: anytype})",
.documentation=
\\ Converts an enum value or union value to a slice of bytes representing the name.
\\If the enum is non-exhaustive and the tag value does not map to a name, it invokes safety-checked Undefined Behavior.
},
.{
.name="@TagType",
.signature="@TagType(T: type) type",
.snippet="@TagType(${1:T: type})",
.documentation=
\\ For an enum, returns the integer type that is used to store the enumeration value.
\\ For a union, returns the enum type that is used to store the tag value.
},
.{
.name="@This",
.signature="@This() type",
.snippet="@This()",
.documentation=
\\ Returns the innermost struct, enum, or union that this function call is inside. This can be useful for an anonymous struct that needs to refer to itself:
\\test.zig
\\```zig
\\const std = @import("std");
\\const expect = std.testing.expect;
\\
\\test "@This()" {
\\ var items = [_]i32{ 1, 2, 3, 4 };
\\ const list = List(i32){ .items = items[0..] };
\\ expect(list.length() == 4);
\\}
\\
\\fn List(comptime T: type) type {
\\ return struct {
\\ const Self = @This();
\\
\\ items: []T,
\\
\\ fn length(self: Self) usize {
\\ return self.items.len;
\\ }
\\ };
\\}
\\```
\\```zig
\\$ zig test test.zig
\\1/1 test "@This()"... OK
\\All 1 tests passed.
\\
\\```
\\ When @This() is used at global scope, it returns a reference to the struct that corresponds to the current file.
\\ For structs, unions, enums, and error sets, the fields are guaranteed to be in the same order as declared. For declarations, the order is unspecified.
},
.{
.name="@typeName",
.signature="@typeName(T: type) [N]u8",
.snippet="@typeName(${1:T: type})",
.documentation=
\\ This function returns the string representation of a type, as an array. It is equivalent to a string literal of the type name.
},
.{
.name="@TypeOf",
.signature="@TypeOf(...) type",
.snippet="@TypeOf(${1:...})",
.documentation=
\\ @TypeOf is a special builtin function that takes any (nonzero) number of expressions as parameters and returns the type of the result, using Peer Type Resolution.
\\ The expressions are evaluated, however they are guaranteed to have no runtime side-effects:
