Every suspend point in an async function represents a point at which the coroutine could be destroyed. If that happens, {#syntax#}defer{#endsyntax#} expressions that are in scope are run, as well as {#syntax#}errdefer{#endsyntax#} expressions.

{#link|Await#} counts as a suspend point.

Upon entering a {#syntax#}suspend{#endsyntax#} block, the coroutine is already considered suspended, and can be resumed. For example, if you started another kernel thread, and had that thread call {#syntax#}resume{#endsyntax#} on the promise handle provided by the {#syntax#}suspend{#endsyntax#} block, the new thread would begin executing after the suspend block, while the old thread continued executing the suspend block.

However, the coroutine can be directly resumed from the suspend block, in which case it never returns to its resumer and continues executing.

• Async functions have optimizations disabled - even in release modes - due to an LLVM bug.
• There are some situations where we can know statically that there will not be memory allocation failure, but Zig still forces us to handle it. TODO file an issue for this and link it here.
• Zig does not take advantage of LLVM's allocation elision optimization for coroutines. It crashed LLVM when I tried to do it the first time. This is related to the other 2 bullet points here. See #802.

Builtin functions are provided by the compiler and are prefixed with @. The {#syntax#}comptime{#endsyntax#} keyword on a parameter means that the parameter must be known at compile time.

{#syntax#}@addWithOverflow(comptime T: type, a: T, b: T, result: *T) bool{#endsyntax#}

Performs {#syntax#}result.* = a + b{#endsyntax#}. If overflow or underflow occurs, stores the overflowed bits in {#syntax#}result{#endsyntax#} and returns {#syntax#}true{#endsyntax#}. If no overflow or underflow occurs, returns {#syntax#}false{#endsyntax#}.

{#syntax#}@alignCast(comptime alignment: u29, ptr: var) var{#endsyntax#}

{#syntax#}ptr{#endsyntax#} can be {#syntax#}*T{#endsyntax#}, {#syntax#}fn(){#endsyntax#}, {#syntax#}?*T{#endsyntax#}, {#syntax#}?fn(){#endsyntax#}, or {#syntax#}[]T{#endsyntax#}. It returns the same type as {#syntax#}ptr{#endsyntax#} except with the alignment adjusted to the new value.

A {#link|pointer alignment safety check|Incorrect Pointer Alignment#} is added to the generated code to make sure the pointer is aligned as promised.

{#syntax#}@alignOf(comptime T: type) comptime_int{#endsyntax#}

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.

{#syntax#}const assert = @import("std").debug.assert;
comptime {
    assert(*u32 == *align(@alignOf(u32)) u32);
}{#endsyntax#}

The result is a target-specific compile time constant. It is guaranteed to be less than or equal to {#link|@sizeOf(T)|@sizeOf#}.

{#syntax#}@ArgType(comptime T: type, comptime n: usize) type{#endsyntax#}

This builtin function takes a function type and returns the type of the parameter at index {#syntax#}n{#endsyntax#}.

{#syntax#}T{#endsyntax#} must be a function type.

Note: This function is deprecated. Use {#link|@typeInfo#} instead.

{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}

This builtin function atomically dereferences a pointer and returns the value.

{#syntax#}T{#endsyntax#} must be a pointer type, a {#syntax#}bool{#endsyntax#}, or an integer whose bit count meets these requirements:

• At least 8
• At most the same as usize
• Power of 2

TODO right now bool is not accepted. Also I think we could make non powers of 2 work fine, maybe we can remove this restriction

{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}

This builtin function atomically modifies memory and then returns the previous value.

{#syntax#}T{#endsyntax#} must be a pointer type, a {#syntax#}bool{#endsyntax#}, or an integer whose bit count meets these requirements:

• At least 8
• At most the same as usize
• Power of 2

TODO right now bool is not accepted. Also I think we could make non powers of 2 work fine, maybe we can remove this restriction

{#syntax#}@bitCast(comptime DestType: type, value: var) DestType{#endsyntax#}

Converts a value of one type to another type.

Asserts that {#syntax#}@sizeOf(@typeOf(value)) == @sizeOf(DestType){#endsyntax#}.

Asserts that {#syntax#}@typeId(DestType) != @import("builtin").TypeId.Pointer{#endsyntax#}. Use {#syntax#}@ptrCast{#endsyntax#} or {#syntax#}@intToPtr{#endsyntax#} if you need this.

Can be used for these things for example:

• Convert {#syntax#}f32{#endsyntax#} to {#syntax#}u32{#endsyntax#} bits
• Convert {#syntax#}i32{#endsyntax#} to {#syntax#}u32{#endsyntax#} preserving twos complement

Works at compile-time if {#syntax#}value{#endsyntax#} is known at compile time. It's a compile error to bitcast a struct to a scalar type of the same size since structs have undefined layout. However if the struct is packed then it works.

{#syntax#}@bitOffsetOf(comptime T: type, comptime field_name: [] const u8) comptime_int{#endsyntax#}

Returns the bit offset of a field relative to its containing struct.

For non {#link|packed structs|packed struct#}, this will always be divisible by {#syntax#}8{#endsyntax#}. For packed structs, non-byte-aligned fields will share a byte offset, but they will have different bit offsets.

{#syntax#}@boolToInt(value: bool) u1{#endsyntax#}

Converts {#syntax#}true{#endsyntax#} to {#syntax#}u1(1){#endsyntax#} and {#syntax#}false{#endsyntax#} to {#syntax#}u1(0){#endsyntax#}.

If the value is known at compile-time, the return type is {#syntax#}comptime_int{#endsyntax#} instead of {#syntax#}u1{#endsyntax#}.

{#syntax#}@breakpoint(){#endsyntax#}

This function inserts a platform-specific debug trap instruction which causes debuggers to break there.

This function is only valid within function scope.

{#syntax#}@bswap(comptime T: type, value: T) T{#endsyntax#}

{#syntax#}T{#endsyntax#} must be an integer type with bit count evenly divisible by 8.

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.

{#syntax#}@bitreverse(comptime T: type, value: T) T{#endsyntax#}

{#syntax#}T{#endsyntax#} accepts any integer type.

Reverses the bitpattern of an integer value, including the sign bit if applicable.

For example 0b10110110 ({#syntax#}u8 = 182{#endsyntax#}, {#syntax#}i8 = -74{#endsyntax#}) becomes 0b01101101 ({#syntax#}u8 = 109{#endsyntax#}, {#syntax#}i8 = 109{#endsyntax#}).

{#syntax#}@byteOffsetOf(comptime T: type, comptime field_name: [] const u8) comptime_int{#endsyntax#}

Returns the byte offset of a field relative to its containing struct.

{#syntax#}@bytesToSlice(comptime Element: type, bytes: []u8) []Element{#endsyntax#}

Converts a slice of bytes or array of bytes into a slice of {#syntax#}Element{#endsyntax#}. The resulting slice has the same {#link|pointer|Pointers#} properties as the parameter.

Attempting to convert a number of bytes with a length that does not evenly divide into a slice of elements results in safety-protected {#link|Undefined Behavior#}.

{#syntax#}@cDefine(comptime name: []u8, value){#endsyntax#}

This function can only occur inside {#syntax#}@cImport{#endsyntax#}.

This appends #define $name $value to the {#syntax#}@cImport{#endsyntax#} temporary buffer.

To define without a value, like this:

#define _GNU_SOURCE

Use the void value, like this:

{#syntax#}@cDefine("_GNU_SOURCE", {}){#endsyntax#}

{#syntax#}@cImport(expression) (namespace){#endsyntax#}

This function parses C code and imports the functions, types, variables, and compatible macro definitions into the result namespace.

{#syntax#}expression{#endsyntax#} is interpreted at compile time. The builtin functions {#syntax#}@cInclude{#endsyntax#}, {#syntax#}@cDefine{#endsyntax#}, and {#syntax#}@cUndef{#endsyntax#} work within this expression, appending to a temporary buffer which is then parsed as C code.

Usually you should only have one {#syntax#}@cImport{#endsyntax#} 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 {#syntax#}@cImport{#endsyntax#} expressions would be:

• To avoid a symbol collision, for example if foo.h and bar.h both #define CONNECTION_COUNT
• To analyze the C code with different preprocessor defines

{#syntax#}@cInclude(comptime path: []u8){#endsyntax#}

This function can only occur inside {#syntax#}@cImport{#endsyntax#}.

This appends #include <$path>\n to the {#syntax#}c_import{#endsyntax#} temporary buffer.

{#syntax#}@clz(x: T) U{#endsyntax#}

This function counts the number of leading zeroes in {#syntax#}x{#endsyntax#} which is an integer type {#syntax#}T{#endsyntax#}.

The return type {#syntax#}U{#endsyntax#} is an unsigned integer with the minimum number of bits that can represent the value {#syntax#}T.bit_count{#endsyntax#}.

If {#syntax#}x{#endsyntax#} is zero, {#syntax#}@clz{#endsyntax#} returns {#syntax#}T.bit_count{#endsyntax#}.

{#syntax#}@cmpxchgStrong(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T{#endsyntax#}

This function performs a strong atomic compare exchange operation. It's the equivalent of this code, except atomic:

If you are using cmpxchg in a loop, {#link|@cmpxchgWeak#} is the better choice, because it can be implemented more efficiently in machine instructions.

{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("builtin").AtomicOrder{#endsyntax#}.

{#syntax#}@typeOf(ptr).alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}

{#syntax#}@cmpxchgWeak(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T{#endsyntax#}

This function performs a weak atomic compare exchange operation. It's the equivalent of this code, except atomic:

If you are using cmpxchg in a loop, the sporadic failure will be no problem, and {#syntax#}cmpxchgWeak{#endsyntax#} is the better choice, because it can be implemented more efficiently in machine instructions. However if you need a stronger guarantee, use {#link|@cmpxchgStrong#}.

{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("builtin").AtomicOrder{#endsyntax#}.

{#syntax#}@typeOf(ptr).alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}

{#syntax#}@compileError(comptime msg: []u8){#endsyntax#}

This function, when semantically analyzed, causes a compile error with the message {#syntax#}msg{#endsyntax#}.

There are several ways that code avoids being semantically checked, such as using {#syntax#}if{#endsyntax#} or {#syntax#}switch{#endsyntax#} with compile time constants, and {#syntax#}comptime{#endsyntax#} functions.

{#syntax#}@compileLog(args: ...){#endsyntax#}

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.

will ouput:

If all {#syntax#}@compileLog{#endsyntax#} calls are removed or not encountered by analysis, the program compiles successfully and the generated executable prints:

{#syntax#}@ctz(x: T) U{#endsyntax#}

This function counts the number of trailing zeroes in {#syntax#}x{#endsyntax#} which is an integer type {#syntax#}T{#endsyntax#}.

The return type {#syntax#}U{#endsyntax#} is an unsigned integer with the minimum number of bits that can represent the value {#syntax#}T.bit_count{#endsyntax#}.

If {#syntax#}x{#endsyntax#} is zero, {#syntax#}@ctz{#endsyntax#} returns {#syntax#}T.bit_count{#endsyntax#}.

{#syntax#}@cUndef(comptime name: []u8){#endsyntax#}

This function can only occur inside {#syntax#}@cImport{#endsyntax#}.

This appends #undef $name to the {#syntax#}@cImport{#endsyntax#} temporary buffer.

{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}

Exact division. Caller guarantees {#syntax#}denominator != 0{#endsyntax#} and {#syntax#}@divTrunc(numerator, denominator) * denominator == numerator{#endsyntax#}.

• {#syntax#}@divExact(6, 3) == 2{#endsyntax#}
• {#syntax#}@divExact(a, b) * b == a{#endsyntax#}

For a function that returns a possible error code, use {#syntax#}@import("std").math.divExact{#endsyntax#}.

{#syntax#}@divFloor(numerator: T, denominator: T) T{#endsyntax#}

Floored division. Rounds toward negative infinity. For unsigned integers it is the same as {#syntax#}numerator / denominator{#endsyntax#}. Caller guarantees {#syntax#}denominator != 0{#endsyntax#} and {#syntax#}!(@typeId(T) == builtin.TypeId.Int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1){#endsyntax#}.

• {#syntax#}@divFloor(-5, 3) == -2{#endsyntax#}
• {#syntax#}@divFloor(a, b) + @mod(a, b) == a{#endsyntax#}

For a function that returns a possible error code, use {#syntax#}@import("std").math.divFloor{#endsyntax#}.

{#syntax#}@divTrunc(numerator: T, denominator: T) T{#endsyntax#}

Truncated division. Rounds toward zero. For unsigned integers it is the same as {#syntax#}numerator / denominator{#endsyntax#}. Caller guarantees {#syntax#}denominator != 0{#endsyntax#} and {#syntax#}!(@typeId(T) == builtin.TypeId.Int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1){#endsyntax#}.

• {#syntax#}@divTrunc(-5, 3) == -1{#endsyntax#}
• {#syntax#}@divTrunc(a, b) + @rem(a, b) == a{#endsyntax#}

For a function that returns a possible error code, use {#syntax#}@import("std").math.divTrunc{#endsyntax#}.

{#syntax#}@embedFile(comptime path: []const u8) [X]u8{#endsyntax#}

This function returns a compile time constant fixed-size array with length equal to the byte count of the file given by {#syntax#}path{#endsyntax#}. The contents of the array are the contents of the file.

{#syntax#}path{#endsyntax#} is absolute or relative to the current file, just like {#syntax#}@import{#endsyntax#}.

{#syntax#}@enumToInt(enum_value: var) var{#endsyntax#}

Converts an enumeration value into its integer tag type.

If the enum has only 1 possible value, the resut is a {#syntax#}comptime_int{#endsyntax#} known at {#link|comptime#}.

{#syntax#}@errorName(err: anyerror) []const u8{#endsyntax#}

This function returns the string representation of an error. The string representation of {#syntax#}error.OutOfMem{#endsyntax#} is {#syntax#}"OutOfMem"{#endsyntax#}.

If there are no calls to {#syntax#}@errorName{#endsyntax#} in an entire application, or all calls have a compile-time known value for {#syntax#}err{#endsyntax#}, then no error name table will be generated.

{#syntax#}@errorReturnTrace() ?*builtin.StackTrace{#endsyntax#}

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`.

{#syntax#}@errorToInt(err: var) @IntType(false, @sizeOf(anyerror) * 8){#endsyntax#}

Supports the following types:

• {#link|The Global Error Set#}
• {#link|Error Set Type#}
• {#link|Error Union Type#}

Converts an error to the integer representation of an error.

It is generally recommended to avoid this cast, as the integer representation of an error is not stable across source code changes.

{#syntax#}@errSetCast(comptime T: DestType, value: var) DestType{#endsyntax#}

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 {#link|Undefined Behavior#}.

{#syntax#}@export(comptime name: []const u8, target: var, linkage: builtin.GlobalLinkage) []const u8{#endsyntax#}

Creates a symbol in the output object file.

{#syntax#}@fence(order: AtomicOrder){#endsyntax#}

The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.

{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("builtin").AtomicOrder{#endsyntax#}.

{#syntax#}@field(lhs: var, comptime field_name: []const u8) (field){#endsyntax#}

Preforms field access equivalent to {#syntax#}lhs.field_name{#endsyntax#}, except instead of the field {#syntax#}"field_name"{#endsyntax#}, it accesses the field named by the string value of {#syntax#}field_name{#endsyntax#}.

{#syntax#}@fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8,
    field_ptr: *T) *ParentType{#endsyntax#}

Given a pointer to a field, returns the base pointer of a struct.

{#syntax#}@floatCast(comptime DestType: type, value: var) DestType{#endsyntax#}

Convert from one float type to another. This cast is safe, but may cause the numeric value to lose precision.

{#syntax#}@floatToInt(comptime DestType: type, float: var) DestType{#endsyntax#}

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 {#link|Undefined Behavior#}.

{#syntax#}@frameAddress(){#endsyntax#}

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.

{#syntax#}@handle(){#endsyntax#}

This function returns a {#syntax#}promise->T{#endsyntax#} type, where {#syntax#}T{#endsyntax#} is the return type of the async function in scope.

This function is only valid within an async function scope.

{#syntax#}@import(comptime path: []u8) (namespace){#endsyntax#}

This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and imports all the public top level declarations into the resulting namespace.

{#syntax#}path{#endsyntax#} can be a relative or absolute 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 {#syntax#}@import{#endsyntax#} function call.

The following packages are always available:

• {#syntax#}@import("std"){#endsyntax#} - Zig Standard Library
• {#syntax#}@import("builtin"){#endsyntax#} - Compiler-provided types and variables

{#syntax#}@inlineCall(function: X, args: ...) Y{#endsyntax#}

This calls a function, in the same way that invoking an expression with parentheses does:

Unlike a normal function call, however, {#syntax#}@inlineCall{#endsyntax#} guarantees that the call will be inlined. If the call cannot be inlined, a compile error is emitted.

{#syntax#}@intCast(comptime DestType: type, int: var) DestType{#endsyntax#}

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 {#link|Undefined Behavior#}.

{#syntax#}@intToEnum(comptime DestType: type, int_value: @TagType(DestType)) DestType{#endsyntax#}

Converts an integer into an {#link|enum#} value.

Attempting to convert an integer which represents no value in the chosen enum type invokes safety-checked {#link|Undefined Behavior#}.

{#syntax#}@intToError(value: @IntType(false, @sizeOf(anyerror) * 8)) anyerror{#endsyntax#}

Converts from the integer representation of an error into {#link|The Global Error Set#} type.

It is generally recommended to avoid this cast, as the integer representation of an error is not stable across source code changes.

Attempting to convert an integer that does not correspond to any error results in safety-protected {#link|Undefined Behavior#}.

{#syntax#}@intToFloat(comptime DestType: type, int: var) DestType{#endsyntax#}

Converts an integer to the closest floating point representation. To convert the other way, use {#link|@floatToInt#}. This cast is always safe.

{#syntax#}@intToPtr(comptime DestType: type, int: usize) DestType{#endsyntax#}

Converts an integer to a pointer. To convert the other way, use {#link|@ptrToInt#}.

{#syntax#}@IntType(comptime is_signed: bool, comptime bit_count: u16) type{#endsyntax#}

This function returns an integer type with the given signness and bit count. The maximum bit count for an integer type is {#syntax#}65535{#endsyntax#}.

{#syntax#}@memberCount(comptime T: type) comptime_int{#endsyntax#}

This function returns the number of members in a struct, enum, or union type.

The result is a compile time constant.

It does not include functions, variables, or constants.

{#syntax#}@memberName(comptime T: type, comptime index: usize) [N]u8{#endsyntax#}

Returns the field name of a struct, union, or enum.

The result is a compile time constant.

It does not include functions, variables, or constants.

{#syntax#}@memberType(comptime T: type, comptime index: usize) type{#endsyntax#}

Returns the field type of a struct or union.

{#syntax#}@memcpy(noalias dest: [*]u8, noalias source: [*]const u8, byte_count: usize){#endsyntax#}

This function copies bytes from one region of memory to another. {#syntax#}dest{#endsyntax#} and {#syntax#}source{#endsyntax#} are both pointers and must not overlap.

This function is a low level intrinsic with no safety mechanisms. Most code should not use this function, instead using something like this:

{#syntax#}for (source[0..byte_count]) |b, i| dest[i] = b;{#endsyntax#}

The optimizer is intelligent enough to turn the above snippet into a memcpy.

There is also a standard library function for this:

{#syntax#}const mem = @import("std").mem;
mem.copy(u8, dest[0..byte_count], source[0..byte_count]);{#endsyntax#}

{#syntax#}@memset(dest: [*]u8, c: u8, byte_count: usize){#endsyntax#}

This function sets a region of memory to {#syntax#}c{#endsyntax#}. {#syntax#}dest{#endsyntax#} 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:

{#syntax#}for (dest[0..byte_count]) |*b| b.* = c;{#endsyntax#}

The optimizer is intelligent enough to turn the above snippet into a memset.

There is also a standard library function for this:

{#syntax#}const mem = @import("std").mem;
mem.set(u8, dest, c);{#endsyntax#}

{#syntax#}@mod(numerator: T, denominator: T) T{#endsyntax#}

Modulus division. For unsigned integers this is the same as {#syntax#}numerator % denominator{#endsyntax#}. Caller guarantees {#syntax#}denominator > 0{#endsyntax#}.

• {#syntax#}@mod(-5, 3) == 1{#endsyntax#}
• {#syntax#}@divFloor(a, b) + @mod(a, b) == a{#endsyntax#}

For a function that returns an error code, see {#syntax#}@import("std").math.mod{#endsyntax#}.

{#syntax#}@mulWithOverflow(comptime T: type, a: T, b: T, result: *T) bool{#endsyntax#}

Performs {#syntax#}result.* = a * b{#endsyntax#}. If overflow or underflow occurs, stores the overflowed bits in {#syntax#}result{#endsyntax#} and returns {#syntax#}true{#endsyntax#}. If no overflow or underflow occurs, returns {#syntax#}false{#endsyntax#}.

{#syntax#}@newStackCall(new_stack: []u8, function: var, args: ...) var{#endsyntax#}

This calls a function, in the same way that invoking an expression with parentheses does. However, instead of using the same stack as the caller, the function uses the stack provided in the {#syntax#}new_stack{#endsyntax#} parameter.

{#syntax#}@noInlineCall(function: var, args: ...) var{#endsyntax#}

This calls a function, in the same way that invoking an expression with parentheses does:

Unlike a normal function call, however, {#syntax#}@noInlineCall{#endsyntax#} guarantees that the call will not be inlined. If the call must be inlined, a compile error is emitted.

{#syntax#}@OpaqueType() type{#endsyntax#}

Creates a new type with an unknown (but non-zero) size and alignment.

This is typically used for type safety when interacting with C code that does not expose struct details. Example:

{#syntax#}@panic(message: []const u8) noreturn{#endsyntax#}

Invokes the panic handler function. By default the panic handler function calls the public {#syntax#}panic{#endsyntax#} function exposed in the root source file, or if there is not one specified, invokes the one provided in {#syntax#}std/special/panic.zig{#endsyntax#}.

Generally it is better to use {#syntax#}@import("std").debug.panic{#endsyntax#}. However, {#syntax#}@panic{#endsyntax#} can be useful for 2 scenarios:

• From library code, calling the programmer's panic function if they exposed one in the root source file.
• When mixing C and Zig code, calling the canonical panic implementation across multiple .o files.

{#syntax#}@popCount(integer: var) var{#endsyntax#}

Counts the number of bits set in an integer.

If {#syntax#}integer{#endsyntax#} is known at {#link|comptime#}, the return type is {#syntax#}comptime_int{#endsyntax#}. Otherwise, the return type is an unsigned integer with the minimum number of bits that can represent the bit count of the integer type.

{#syntax#}@ptrCast(comptime DestType: type, value: var) DestType{#endsyntax#}

Converts a pointer of one type to a pointer of another type.

{#syntax#}@ptrToInt(value: var) usize{#endsyntax#}

Converts {#syntax#}value{#endsyntax#} to a {#syntax#}usize{#endsyntax#} which is the address of the pointer. {#syntax#}value{#endsyntax#} can be one of these types:

• {#syntax#}*T{#endsyntax#}
• {#syntax#}?*T{#endsyntax#}
• {#syntax#}fn(){#endsyntax#}
• {#syntax#}?fn(){#endsyntax#}

To convert the other way, use {#link|@intToPtr#}

{#syntax#}@rem(numerator: T, denominator: T) T{#endsyntax#}

Remainder division. For unsigned integers this is the same as {#syntax#}numerator % denominator{#endsyntax#}. Caller guarantees {#syntax#}denominator > 0{#endsyntax#}.

• {#syntax#}@rem(-5, 3) == -2{#endsyntax#}
• {#syntax#}@divTrunc(a, b) + @rem(a, b) == a{#endsyntax#}

For a function that returns an error code, see {#syntax#}@import("std").math.rem{#endsyntax#}.

{#syntax#}@returnAddress(){#endsyntax#}

This function returns a pointer to the return address of the current stack frame.

The implications of this are target specific and not consistent across all platforms.

This function is only valid within function scope.

{#syntax#}@setAlignStack(comptime alignment: u29){#endsyntax#}

Ensures that a function will have a stack alignment of at least {#syntax#}alignment{#endsyntax#} bytes.

{#syntax#}@setCold(is_cold: bool){#endsyntax#}

Tells the optimizer that a function is rarely called.

{#syntax#}@setEvalBranchQuota(new_quota: usize){#endsyntax#}

Changes the maximum number of backwards branches that compile-time code execution can use before giving up and making a compile error.

If the {#syntax#}new_quota{#endsyntax#} is smaller than the default quota ({#syntax#}1000{#endsyntax#}) or a previously explicitly set quota, it is ignored.

Example:

Now we use {#syntax#}@setEvalBranchQuota{#endsyntax#}:

{#syntax#}@setFloatMode(mode: @import("builtin").FloatMode){#endsyntax#}

Sets the floating point mode of the current scope. Possible values are:

• {#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
• {#syntax#}Optimized{#endsyntax#} - Floating point operations may do all of the following:
  • Assume the arguments and result are not NaN. Optimizations are required to retain defined behavior over NaNs, but the value of the result is undefined.
  • Assume the arguments and result are not +/-Inf. Optimizations are required to retain defined behavior over +/-Inf, but the value of the result is undefined.
  • Treat the sign of a zero argument or result as insignificant.
  • Use the reciprocal of an argument rather than perform division.
  • Perform floating-point contraction (e.g. fusing a multiply followed by an addition into a fused multiply-and-add).
  • Perform algebraically equivalent transformations that may change results in floating point (e.g. reassociate).
  This is equivalent to -ffast-math in GCC.

The floating point mode is inherited by child scopes, and can be overridden in any scope. You can set the floating point mode in a struct or module scope by using a comptime block.

{#syntax#}@setGlobalLinkage(global_variable_name, comptime linkage: GlobalLinkage){#endsyntax#}

{#syntax#}GlobalLinkage{#endsyntax#} can be found with {#syntax#}@import("builtin").GlobalLinkage{#endsyntax#}.

{#syntax#}@setRuntimeSafety(safety_on: bool){#endsyntax#}

Sets whether runtime safety checks are on for the scope that contains the function call.

{#syntax#}@shlExact(value: T, shift_amt: Log2T) T{#endsyntax#}

Performs the left shift operation ({#syntax#}<<{#endsyntax#}). Caller guarantees that the shift will not shift any 1 bits out.

The type of {#syntax#}shift_amt{#endsyntax#} is an unsigned integer with {#syntax#}log2(T.bit_count){#endsyntax#} bits. This is because {#syntax#}shift_amt >= T.bit_count{#endsyntax#} is undefined behavior.

{#syntax#}@shlWithOverflow(comptime T: type, a: T, shift_amt: Log2T, result: *T) bool{#endsyntax#}

Performs {#syntax#}result.* = a << b{#endsyntax#}. If overflow or underflow occurs, stores the overflowed bits in {#syntax#}result{#endsyntax#} and returns {#syntax#}true{#endsyntax#}. If no overflow or underflow occurs, returns {#syntax#}false{#endsyntax#}.

The type of {#syntax#}shift_amt{#endsyntax#} is an unsigned integer with {#syntax#}log2(T.bit_count){#endsyntax#} bits. This is because {#syntax#}shift_amt >= T.bit_count{#endsyntax#} is undefined behavior.

{#syntax#}@shrExact(value: T, shift_amt: Log2T) T{#endsyntax#}

Performs the right shift operation ({#syntax#}>>{#endsyntax#}). Caller guarantees that the shift will not shift any 1 bits out.

The type of {#syntax#}shift_amt{#endsyntax#} is an unsigned integer with {#syntax#}log2(T.bit_count){#endsyntax#} bits. This is because {#syntax#}shift_amt >= T.bit_count{#endsyntax#} is undefined behavior.

{#syntax#}@sizeOf(comptime T: type) comptime_int{#endsyntax#}

This function returns the number of bytes it takes to store {#syntax#}T{#endsyntax#} in memory.

The result is a target-specific compile time constant.

{#syntax#}@sliceToBytes(value: var) []u8{#endsyntax#}

Converts a slice or array to a slice of {#syntax#}u8{#endsyntax#}. The resulting slice has the same {#link|pointer|Pointers#} properties as the parameter.

{#syntax#}@sqrt(comptime T: type, value: T) T{#endsyntax#}

Performs the square root of a floating point number. Uses a dedicated hardware instruction when available. Currently only supports f32 and f64 at runtime. f128 at runtime is TODO.

This is a low-level intrinsic. Most code can use {#syntax#}std.math.sqrt{#endsyntax#} instead.

{#syntax#}@subWithOverflow(comptime T: type, a: T, b: T, result: *T) bool{#endsyntax#}

Performs {#syntax#}result.* = a - b{#endsyntax#}. If overflow or underflow occurs, stores the overflowed bits in {#syntax#}result{#endsyntax#} and returns {#syntax#}true{#endsyntax#}. If no overflow or underflow occurs, returns {#syntax#}false{#endsyntax#}.

{#syntax#}@tagName(value: var) []const u8{#endsyntax#}

Converts an enum value or union value to a slice of bytes representing the name.

{#syntax#}@TagType(T: type) type{#endsyntax#}

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.

{#syntax#}@This() type{#endsyntax#}

Returns the innermost struct or union that this function call is inside. This can be useful for an anonymous struct that needs to refer to itself:

When {#syntax#}@This(){#endsyntax#} is used at global scope, it returns a reference to the current import. There is a proposal to remove the import type and use an empty struct type instead. See #1047 for details.

{#syntax#}@truncate(comptime T: type, integer) T{#endsyntax#}

This function truncates bits from an integer type, resulting in a smaller integer type.

The following produces a crash in debug mode and undefined behavior in release mode:

{#syntax#}const a: u16 = 0xabcd;
const b: u8 = u8(a);{#endsyntax#}

However this is well defined and working code:

{#syntax#}const a: u16 = 0xabcd;
const b: u8 = @truncate(u8, a);
// b is now 0xcd{#endsyntax#}

This function always truncates the significant bits of the integer, regardless of endianness on the target platform.

{#syntax#}@typeId(comptime T: type) @import("builtin").TypeId{#endsyntax#}

Returns which kind of type something is. Possible values:

{#syntax#}@typeInfo(comptime T: type) @import("builtin").TypeInfo{#endsyntax#}

Returns information on the type. Returns a value of the following union:

{#syntax#}@typeName(T: type) [N]u8{#endsyntax#}

This function returns the string representation of a type, as an array. It is equivalent to a string literal of the type name.

{#syntax#}@typeOf(expression) type{#endsyntax#}

This function returns a compile-time constant, which is the type of the expression passed as an argument. The expression is evaluated.

{#syntax#}@Vector(comptime len: u32, comptime ElemType: type) type{#endsyntax#}

This function returns a vector type for {#link|SIMD#}.

{#syntax#}ElemType{#endsyntax#} must be an {#link|integer|Integers#}, a {#link|float|Floats#}, or a {#link|pointer|Pointers#}.

Zig has four build modes:

• {#link|Debug#} (default)
• {#link|ReleaseFast#}
• {#link|ReleaseSafe#}
• {#link|ReleaseSmall#}

To add standard build options to a build.zig file:

This causes these options to be available:

  -Drelease-safe=[bool] optimizations on and safety on
  -Drelease-fast=[bool] optimizations on and safety off
  -Drelease-small=[bool] size optimizations on and safety off

$ zig build-exe example.zig

• Fast compilation speed
• Safety checks enabled
• Slow runtime performance
• Large binary size
• No reproducible build requirement

$ zig build-exe example.zig --release-fast

• Fast runtime performance
• Safety checks disabled
• Slow compilation speed
• Large binary size
• Reproducible build

$ zig build-exe example.zig --release-safe

• Medium runtime performance
• Safety checks enabled
• Slow compilation speed
• Large binary size
• Reproducible build

$ zig build-exe example.zig --release-small

• Medium runtime performance
• Safety checks disabled
• Slow compilation speed
• Small binary size
• Reproducible build

Zig has a compile option --single-threaded which has the following effects:

• {#link|@atomicLoad#} is emitted as a normal load.
• {#link|@atomicRmw#} is emitted as a normal memory load, modify, store.
• {#link|@fence#} becomes a no-op.
• Variables which have Thread Local Storage instead become globals. TODO thread local variables are not implemented yet.
• The overhead of {#link|Coroutines#} becomes equivalent to function call overhead. TODO: please note this will not be implemented until the upcoming Coroutine Rewrite
• The {#syntax#}@import("builtin").single_threaded{#endsyntax#} becomes {#syntax#}true{#endsyntax#} and therefore various userland APIs which read this variable become more efficient. For example {#syntax#}std.Mutex{#endsyntax#} becomes an empty data structure and all of its functions become no-ops.

Zig has many instances of undefined behavior. If undefined behavior is detected at compile-time, Zig emits a compile error and refuses to continue. Most undefined behavior that cannot be detected at compile-time can be detected at runtime. In these cases, Zig has safety checks. Safety checks can be disabled on a per-block basis with {#link|setRuntimeSafety#}. The {#link|ReleaseFast#} build mode disables all safety checks in order to facilitate optimizations.

When a safety check fails, Zig crashes with a stack trace, like this:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

To obtain the maximum value of an unsigned integer, use {#syntax#}std.math.maxInt{#endsyntax#}.

At compile-time:

At runtime:

To truncate bits, use {#link|@truncate#}.

The following operators can cause integer overflow:

• {#syntax#}+{#endsyntax#} (addition)
• {#syntax#}-{#endsyntax#} (subtraction)
• {#syntax#}-{#endsyntax#} (negation)
• {#syntax#}*{#endsyntax#} (multiplication)
• {#syntax#}/{#endsyntax#} (division)
• {#link|@divTrunc#} (division)
• {#link|@divFloor#} (division)
• {#link|@divExact#} (division)

Example with addition at compile-time:

At runtime:

These functions provided by the standard library return possible errors.

• {#syntax#}@import("std").math.add{#endsyntax#}
• {#syntax#}@import("std").math.sub{#endsyntax#}
• {#syntax#}@import("std").math.mul{#endsyntax#}
• {#syntax#}@import("std").math.divTrunc{#endsyntax#}
• {#syntax#}@import("std").math.divFloor{#endsyntax#}
• {#syntax#}@import("std").math.divExact{#endsyntax#}
• {#syntax#}@import("std").math.shl{#endsyntax#}

Example of catching an overflow for addition:

These builtins return a {#syntax#}bool{#endsyntax#} of whether or not overflow occurred, as well as returning the overflowed bits:

• {#link|@addWithOverflow#}
• {#link|@subWithOverflow#}
• {#link|@mulWithOverflow#}
• {#link|@shlWithOverflow#}

Example of {#link|@addWithOverflow#}:

These operations have guaranteed wraparound semantics.

• {#syntax#}+%{#endsyntax#} (wraparound addition)
• {#syntax#}-%{#endsyntax#} (wraparound subtraction)
• {#syntax#}-%{#endsyntax#} (wraparound negation)
• {#syntax#}*%{#endsyntax#} (wraparound multiplication)

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

One way to avoid this crash is to test for null instead of assuming non-null, with the {#syntax#}if{#endsyntax#} expression:

At compile-time:

At runtime:

One way to avoid this crash is to test for an error instead of assuming a successful result, with the {#syntax#}if{#endsyntax#} expression:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

At compile-time:

At runtime:

This safety is not available for {#syntax#}extern{#endsyntax#} or {#syntax#}packed{#endsyntax#} unions.

To change the active field of a union, assign the entire union, like this:

To change the active field of a union when a meaningful value for the field is not known, use {#link|undefined#}, like this:

TODO

TODO: explain no default allocator in zig

TODO: show how to use the allocator interface

TODO: mention debug allocator

TODO: importance of checking for allocation failure

TODO: mention overcommit and the OOM Killer

TODO: mention recursion

Compile variables are accessible by importing the {#syntax#}"builtin"{#endsyntax#} package, which the compiler makes available to every Zig source file. It contains compile-time constants such as the current target, endianness, and release mode.

Example of what is imported with {#syntax#}@import("builtin"){#endsyntax#}:

TODO: explain how root source file finds other files

TODO: pub fn main

TODO: pub fn panic

TODO: if linking with libc you can use export fn main

TODO: order independent top level declarations

TODO: lazy analysis

TODO: using comptime { _ = @import() }

TODO: basic usage

TODO: lazy analysis

TODO: --test-filter

TODO: --test-name-prefix

TODO: testing in releasefast and releasesafe mode. assert still works

TODO: explain purpose, it's supposed to replace make/cmake

TODO: example of building a zig executable

TODO: example of building a C library

Although Zig is independent of C, and, unlike most other languages, does not depend on libc, Zig acknowledges the importance of interacting with existing C code.

There are a few ways that Zig facilitates C interop.

These have guaranteed C ABI compatibility and can be used like any other type.

• {#syntax#}c_short{#endsyntax#}
• {#syntax#}c_ushort{#endsyntax#}
• {#syntax#}c_int{#endsyntax#}
• {#syntax#}c_uint{#endsyntax#}
• {#syntax#}c_long{#endsyntax#}
• {#syntax#}c_ulong{#endsyntax#}
• {#syntax#}c_longlong{#endsyntax#}
• {#syntax#}c_ulonglong{#endsyntax#}
• {#syntax#}c_longdouble{#endsyntax#}
• {#syntax#}c_void{#endsyntax#}

The {#syntax#}@cImport{#endsyntax#} builtin function can be used to directly import symbols from .h files:

The {#syntax#}@cImport{#endsyntax#} function takes an expression as a parameter. This expression is evaluated at compile-time and is used to control preprocessor directives and include multiple .h files:

One of the primary use cases for Zig is exporting a library with the C ABI for other programming languages to call into. The {#syntax#}export{#endsyntax#} keyword in front of functions, variables, and types causes them to be part of the library API:

mathtest.zig

To make a shared library:

$ zig build-lib mathtest.zig

To make a static library:

$ zig build-lib mathtest.zig --static

Here is an example with the {#link|Zig Build System#}:

test.c

// This header is generated by zig from mathtest.zig
#include "mathtest.h"
#include <assert.h>

int main(int argc, char **argv) {
    assert(add(42, 1337) == 1379);
    return 0;
}

build.zig

terminal

$ zig build
$ ./test
$ echo $?
0

You can mix Zig object files with any other object files that respect the C ABI. Example:

base64.zig

test.c

// This header is generated by zig from base64.zig
#include "base64.h"

#include <string.h>
#include <stdio.h>

int main(int argc, char **argv) {
    const char *encoded = "YWxsIHlvdXIgYmFzZSBhcmUgYmVsb25nIHRvIHVz";
    char buf[200];

    size_t len = decode_base_64(buf, 200, encoded, strlen(encoded));
    buf[len] = 0;
    puts(buf);

    return 0;
}

build.zig

terminal

$ zig build
$ ./test
all your base are belong to us

Zig supports generating code for all targets that LLVM supports. Here is what it looks like to execute zig targets on a Linux x86_64 computer:

$ zig targets
Architectures:
  armv8_2a
  armv8_1a
  armv8
  armv8r
  armv8m_baseline
  armv8m_mainline
  armv7
  armv7em
  armv7m
  armv7s
  armv7k
  armv7ve
  armv6
  armv6m
  armv6k
  armv6t2
  armv5
  armv5te
  armv4t
  armeb
  aarch64
  aarch64_be
  avr
  bpfel
  bpfeb
  hexagon
  mips
  mipsel
  mips64
  mips64el
  msp430
  nios2
  powerpc
  powerpc64
  powerpc64le
  r600
  amdgcn
  riscv32
  riscv64
  sparc
  sparcv9
  sparcel
  s390x
  tce
  tcele
  thumb
  thumbeb
  i386
  x86_64 (native)
  xcore
  nvptx
  nvptx64
  le32
  le64
  amdil
  amdil64
  hsail
  hsail64
  spir
  spir64
  kalimbav3
  kalimbav4
  kalimbav5
  shave
  lanai
  wasm32
  wasm64
  renderscript32
  renderscript64

Operating Systems:
  freestanding
  ananas
  cloudabi
  dragonfly
  freebsd
  fuchsia
  ios
  kfreebsd
  linux (native)
  lv2
  macosx
  netbsd
  openbsd
  solaris
  windows
  haiku
  minix
  rtems
  nacl
  cnk
  bitrig
  aix
  cuda
  nvcl
  amdhsa
  ps4
  elfiamcu
  tvos
  watchos
  mesa3d
  contiki
  zen

Environments:
  unknown
  gnu (native)
  gnuabi64
  gnueabi
  gnueabihf
  gnux32
  code16
  eabi
  eabihf
  android
  musl
  musleabi
  musleabihf
  msvc
  itanium
  cygnus
  amdopencl
  coreclr
  opencl

The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating sytsem abstractions, and thus takes additional work to support more platforms. Not all standard library code requires operating system abstractions, however, so things such as generic data structures work an all above platforms.

The current list of targets supported by the Zig Standard Library is:

• Linux x86_64
• Windows x86_64
• MacOS x86_64

These coding conventions are not enforced by the compiler, but they are shipped in this documentation along with the compiler in order to provide a point of reference, should anyone wish to point to an authority on agreed upon Zig coding style.

• 4 space indentation
• Open braces on same line, unless you need to wrap.
• If a list of things is longer than 2, put each item on its own line and exercise the ability to put an extra comma at the end.
• Line length: aim for 100; use common sense.

Roughly speaking: {#syntax#}camelCaseFunctionName{#endsyntax#}, {#syntax#}TitleCaseTypeName{#endsyntax#}, {#syntax#}snake_case_variable_name{#endsyntax#}. More precisely:

• If {#syntax#}x{#endsyntax#} is a {#syntax#}struct{#endsyntax#} (or an alias of a {#syntax#}struct{#endsyntax#}), then {#syntax#}x{#endsyntax#} should be {#syntax#}TitleCase{#endsyntax#}.
• If {#syntax#}x{#endsyntax#} otherwise identifies a type, {#syntax#}x{#endsyntax#} should have {#syntax#}snake_case{#endsyntax#}.
• If {#syntax#}x{#endsyntax#} is callable, and {#syntax#}x{#endsyntax#}'s return type is {#syntax#}type{#endsyntax#}, then {#syntax#}x{#endsyntax#} should be {#syntax#}TitleCase{#endsyntax#}.
• If {#syntax#}x{#endsyntax#} is otherwise callable, then {#syntax#}x{#endsyntax#} should be {#syntax#}camelCase{#endsyntax#}.
• Otherwise, {#syntax#}x{#endsyntax#} should be {#syntax#}snake_case{#endsyntax#}.

Acronyms, initialisms, proper nouns, or any other word that has capitalization rules in written English are subject to naming conventions just like any other word. Even acronyms that are only 2 letters long are subject to these conventions.

These are general rules of thumb; if it makes sense to do something different, do what makes sense. For example, if there is an established convention such as {#syntax#}ENOENT{#endsyntax#}, follow the established convention.

See the Zig Standard Library for more examples.

Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.

Throughout all zig source code (including in comments), some codepoints are never allowed:

• Ascii control characters, except for U+000a (LF): U+0000 - U+0009, U+000b - U+0001f, U+007f. (Note that Windows line endings (CRLF) are not allowed, and hard tabs are not allowed.)
• Non-Ascii Unicode line endings: U+0085 (NEL), U+2028 (LS), U+2029 (PS).

The codepoint U+000a (LF) (which is encoded as the single-byte value 0x0a) is the line terminator character. This character always terminates a line of zig source code (except possbly the last line of the file).

For some discussion on the rationale behind these design decisions, see issue #663

Root <- skip ContainerMembers eof

# *** Top level ***
ContainerMembers
    <- TestDecl ContainerMembers
     / TopLevelComptime ContainerMembers
     / KEYWORD_pub? TopLevelDecl ContainerMembers
     / KEYWORD_pub? ContainerField COMMA ContainerMembers
     / KEYWORD_pub? ContainerField
     /

TestDecl <- KEYWORD_test STRINGLITERAL Block

TopLevelComptime <- KEYWORD_comptime BlockExpr

TopLevelDecl
    <- (KEYWORD_export / KEYWORD_extern STRINGLITERAL? / KEYWORD_inline)? FnProto (SEMICOLON / Block)
     / (KEYWORD_export / KEYWORD_extern STRINGLITERAL?)? VarDecl
     / KEYWORD_use Expr SEMICOLON

FnProto <- FnCC? KEYWORD_fn IDENTIFIER? LPAREN ParamDeclList RPAREN ByteAlign? LinkSection? EXCLAMATIONMARK? (KEYWORD_var / TypeExpr)

VarDecl <- (KEYWORD_const / KEYWORD_var) IDENTIFIER (COLON TypeExpr)? ByteAlign? LinkSection? (EQUAL Expr)? SEMICOLON

ContainerField <- IDENTIFIER (COLON TypeExpr)? (EQUAL Expr)?

# *** Block Level ***
Statement
    <- KEYWORD_comptime? VarDecl
     / KEYWORD_comptime BlockExprStatement
     / KEYWORD_suspend (SEMICOLON / BlockExprStatement)
     / KEYWORD_defer BlockExprStatement
     / KEYWORD_errdefer BlockExprStatement
     / IfStatement
     / LabeledStatement
     / SwitchExpr
     / AssignExpr SEMICOLON

IfStatement
    <- IfPrefix BlockExpr ( KEYWORD_else Payload? Statement )?
     / IfPrefix AssignExpr ( SEMICOLON / KEYWORD_else Payload? Statement )

LabeledStatement <- BlockLabel? (Block / LoopStatement)

LoopStatement <- KEYWORD_inline? (ForStatement / WhileStatement)

ForStatement
    <- ForPrefix BlockExpr ( KEYWORD_else Statement )?
     / ForPrefix AssignExpr ( SEMICOLON / KEYWORD_else Statement )

WhileStatement
    <- WhilePrefix BlockExpr ( KEYWORD_else Payload? Statement )?
     / WhilePrefix AssignExpr ( SEMICOLON / KEYWORD_else Payload? Statement )

BlockExprStatement
    <- BlockExpr
     / AssignExpr SEMICOLON

BlockExpr <- BlockLabel? Block

# *** Expression Level ***
AssignExpr <- Expr (AssignOp Expr)?

Expr <- KEYWORD_try* BoolOrExpr

BoolOrExpr <- BoolAndExpr (KEYWORD_or BoolAndExpr)*

BoolAndExpr <- CompareExpr (KEYWORD_and CompareExpr)*

CompareExpr <- BitwiseExpr (CompareOp BitwiseExpr)?

BitwiseExpr <- BitShiftExpr (BitwiseOp BitShiftExpr)*

BitShiftExpr <- AdditionExpr (BitShiftOp AdditionExpr)*

AdditionExpr <- MultiplyExpr (AdditionOp MultiplyExpr)*

MultiplyExpr <- PrefixExpr (MultiplyOp PrefixExpr)*

PrefixExpr <- PrefixOp* PrimaryExpr

PrimaryExpr
    <- AsmExpr
     / IfExpr
     / KEYWORD_break BreakLabel? Expr?
     / KEYWORD_cancel Expr
     / KEYWORD_comptime Expr
     / KEYWORD_continue BreakLabel?
     / KEYWORD_resume Expr
     / KEYWORD_return Expr?
     / LabeledExpr
     / CurlySuffixExpr

IfExpr <- IfPrefix Expr (KEYWORD_else Payload? Expr)?

LabeledExpr <- BlockLabel? (Block / LoopExpr)

Block <- LBRACE Statement* RBRACE

LoopExpr <- KEYWORD_inline? (ForExpr / WhileExpr)

ForExpr <- ForPrefix Expr (KEYWORD_else Expr)?

WhileExpr <- WhilePrefix Expr (KEYWORD_else Payload? Expr)?

CurlySuffixExpr <- TypeExpr InitList?

InitList
    <- LBRACE FieldInit (COMMA FieldInit)* COMMA? RBRACE
     / LBRACE Expr (COMMA Expr)* COMMA? RBRACE
     / LBRACE RBRACE

TypeExpr <- PrefixTypeOp* ErrorUnionExpr

ErrorUnionExpr <- SuffixExpr (EXCLAMATIONMARK TypeExpr)?

SuffixExpr
    <- AsyncPrefix PrimaryTypeExpr SuffixOp* FnCallArguments
     / PrimaryTypeExpr (SuffixOp / FnCallArguments)*

PrimaryTypeExpr
    <- BUILTINIDENTIFIER FnCallArguments
     / CHAR_LITERAL
     / ContainerDecl
     / ErrorSetDecl
     / FLOAT
     / FnProto
     / GroupedExpr
     / LabeledTypeExpr
     / IDENTIFIER
     / IfTypeExpr
     / INTEGER
     / KEYWORD_anyerror
     / KEYWORD_comptime TypeExpr
     / KEYWORD_error DOT IDENTIFIER
     / KEYWORD_false
     / KEYWORD_null
     / KEYWORD_promise
     / KEYWORD_true
     / KEYWORD_undefined
     / KEYWORD_unreachable
     / STRINGLITERAL
     / SwitchExpr

ContainerDecl <- (KEYWORD_extern / KEYWORD_packed)? ContainerDeclAuto

ErrorSetDecl <- KEYWORD_error LBRACE IdentifierList RBRACE

GroupedExpr <- LPAREN Expr RPAREN

IfTypeExpr <- IfPrefix TypeExpr (KEYWORD_else Payload? TypeExpr)?

LabeledTypeExpr
    <- BlockLabel Block
     / BlockLabel? LoopTypeExpr

LoopTypeExpr <- KEYWORD_inline? (ForTypeExpr / WhileTypeExpr)

ForTypeExpr <- ForPrefix TypeExpr (KEYWORD_else TypeExpr)?

WhileTypeExpr <- WhilePrefix TypeExpr (KEYWORD_else Payload? TypeExpr)?

SwitchExpr <- KEYWORD_switch LPAREN Expr RPAREN LBRACE SwitchProngList RBRACE

# *** Assembly ***
AsmExpr <- KEYWORD_asm KEYWORD_volatile? LPAREN STRINGLITERAL AsmOutput? RPAREN

AsmOutput <- COLON AsmOutputList AsmInput?

AsmOutputItem <- LBRACKET IDENTIFIER RBRACKET STRINGLITERAL LPAREN (MINUSRARROW TypeExpr / IDENTIFIER) RPAREN

AsmInput <- COLON AsmInputList AsmClobbers?

AsmInputItem <- LBRACKET IDENTIFIER RBRACKET STRINGLITERAL LPAREN Expr RPAREN

AsmClobbers <- COLON StringList

# *** Helper grammar ***
BreakLabel <- COLON IDENTIFIER

BlockLabel <- IDENTIFIER COLON

FieldInit <- DOT IDENTIFIER EQUAL Expr

WhileContinueExpr <- COLON LPAREN AssignExpr RPAREN

LinkSection <- KEYWORD_linksection LPAREN Expr RPAREN

# Fn specific
FnCC
    <- KEYWORD_nakedcc
     / KEYWORD_stdcallcc
     / KEYWORD_extern
     / KEYWORD_async (LARROW TypeExpr RARROW)?

ParamDecl <- (KEYWORD_noalias / KEYWORD_comptime)? (IDENTIFIER COLON)? ParamType

ParamType
    <- KEYWORD_var
     / DOT3
     / TypeExpr

# Control flow prefixes
IfPrefix <- KEYWORD_if LPAREN Expr RPAREN PtrPayload?

WhilePrefix <- KEYWORD_while LPAREN Expr RPAREN PtrPayload? WhileContinueExpr?

ForPrefix <- KEYWORD_for LPAREN Expr RPAREN PtrIndexPayload

# Payloads
Payload <- PIPE IDENTIFIER PIPE

PtrPayload <- PIPE ASTERISK? IDENTIFIER PIPE

PtrIndexPayload <- PIPE ASTERISK? IDENTIFIER (COMMA IDENTIFIER)? PIPE


# Switch specific
SwitchProng <- SwitchCase EQUALRARROW PtrPayload? AssignExpr

SwitchCase
    <- SwitchItem (COMMA SwitchItem)* COMMA?
     / KEYWORD_else

SwitchItem <- Expr (DOT3 Expr)?

# Operators
AssignOp
    <- ASTERISKEQUAL
     / SLASHEQUAL
     / PERCENTEQUAL
     / PLUSEQUAL
     / MINUSEQUAL
     / LARROW2EQUAL
     / RARROW2EQUAL
     / AMPERSANDEQUAL
     / CARETEQUAL
     / PIPEEQUAL
     / ASTERISKPERCENTEQUAL
     / PLUSPERCENTEQUAL
     / MINUSPERCENTEQUAL
     / EQUAL

CompareOp
    <- EQUALEQUAL
     / EXCLAMATIONMARKEQUAL
     / LARROW
     / RARROW
     / LARROWEQUAL
     / RARROWEQUAL

BitwiseOp
    <- AMPERSAND
     / CARET
     / PIPE
     / KEYWORD_orelse
     / KEYWORD_catch Payload?

BitShiftOp
    <- LARROW2
     / RARROW2

AdditionOp
    <- PLUS
     / MINUS
     / PLUS2
     / PLUSPERCENT
     / MINUSPERCENT

MultiplyOp
    <- PIPE2
     / ASTERISK
     / SLASH
     / PERCENT
     / ASTERISK2
     / ASTERISKPERCENT

PrefixOp
    <- EXCLAMATIONMARK
     / MINUS
     / TILDE
     / MINUSPERCENT
     / AMPERSAND
     / KEYWORD_try
     / KEYWORD_await

PrefixTypeOp
    <- QUESTIONMARK
     / KEYWORD_promise MINUSRARROW
     / ArrayTypeStart (ByteAlign / KEYWORD_const / KEYWORD_volatile)*
     / PtrTypeStart (KEYWORD_align LPAREN Expr (COLON INTEGER COLON INTEGER)? RPAREN / KEYWORD_const / KEYWORD_volatile)*

SuffixOp
    <- LBRACKET Expr (DOT2 Expr?)? RBRACKET
     / DOT IDENTIFIER
     / DOTASTERISK
     / DOTQUESTIONMARK

AsyncPrefix <- KEYWORD_async (LARROW PrefixExpr RARROW)?

FnCallArguments <- LPAREN ExprList RPAREN

# Ptr specific
ArrayTypeStart <- LBRACKET Expr? RBRACKET

PtrTypeStart
    <- ASTERISK
     / ASTERISK2
     / LBRACKET ASTERISK RBRACKET

# ContainerDecl specific
ContainerDeclAuto <- ContainerDeclType LBRACE ContainerMembers RBRACE

ContainerDeclType
    <- (KEYWORD_struct / KEYWORD_enum) (LPAREN Expr RPAREN)?
     / KEYWORD_union (LPAREN (KEYWORD_enum (LPAREN Expr RPAREN)? / Expr) RPAREN)?

# Alignment
ByteAlign <- KEYWORD_align LPAREN Expr RPAREN

# Lists
IdentifierList <- (IDENTIFIER COMMA)* IDENTIFIER?

SwitchProngList <- (SwitchProng COMMA)* SwitchProng?

AsmOutputList <- (AsmOutputItem COMMA)* AsmOutputItem?

AsmInputList <- (AsmInputItem COMMA)* AsmInputItem?

StringList <- (STRINGLITERAL COMMA)* STRINGLITERAL?

ParamDeclList <- (ParamDecl COMMA)* ParamDecl?

ExprList <- (Expr COMMA)* Expr?

# *** Tokens ***
eof <- !.
hex <- [0-9a-fA-F]
char_escape
    <- "\\x" hex hex
     / "\\u" hex hex hex hex
     / "\\U" hex hex hex hex hex hex
     / "\\" [nr\\t'"]
char_char
    <- char_escape
     / [^\\'\n]
string_char
    <- char_escape
     / [^\\"\n]

line_comment <- '//'[^\n]*
line_string <- ("\\\\" [^\n]* [ \n]*)+
line_cstring <- ("c\\\\" [^\n]* [ \n]*)+
skip <- ([ \n] / line_comment)*

CHAR_LITERAL <- "'" char_char "'" skip
FLOAT
    <- "0b" [01]+  "." [01]+  ([eE] [-+]? [01]+)?  skip
     / "0o" [0-7]+ "." [0-7]+ ([eE] [-+]? [0-7]+)? skip
     / "0x" hex+   "." hex+   ([pP] [-+]? hex+)?   skip
     /      [0-9]+ "." [0-9]+ ([eE] [-+]? [0-9]+)? skip
     / "0b" [01]+  "."? [eE] [-+]? [01]+  skip
     / "0o" [0-7]+ "."? [eE] [-+]? [0-7]+ skip
     / "0x" hex+   "."? [pP] [-+]? hex+   skip
     /      [0-9]+ "."? [eE] [-+]? [0-9]+ skip
INTEGER
    <- "0b" [01]+  skip
     / "0o" [0-7]+ skip
     / "0x" hex+   skip
     /      [0-9]+ skip
STRINGLITERAL
    <- "c"? "\"" string_char* "\"" skip
     / line_string                 skip
     / line_cstring                skip
IDENTIFIER
    <- !keyword ("c" !["\\] / [A-Zabd-z_]) [A-Za-z0-9_]* skip
     / "@\"" string_char* "\""                            skip
BUILTINIDENTIFIER <- "@"[A-Za-z_][A-Za-z0-9_]* skip


AMPERSAND            <- '&'      ![=]      skip
AMPERSANDEQUAL       <- '&='               skip
ASTERISK             <- '*'      ![*%=]    skip
ASTERISK2            <- '**'               skip
ASTERISKEQUAL        <- '*='               skip
ASTERISKPERCENT      <- '*%'     ![=]      skip
ASTERISKPERCENTEQUAL <- '*%='              skip
CARET                <- '^'      ![=]      skip
CARETEQUAL           <- '^='               skip
COLON                <- ':'                skip
COMMA                <- ','                skip
DOT                  <- '.'      ![*.?]    skip
DOT2                 <- '..'     ![.]      skip
DOT3                 <- '...'              skip
DOTASTERISK          <- '.*'               skip
DOTQUESTIONMARK      <- '.?'               skip
EQUAL                <- '='      ![>=]     skip
EQUALEQUAL           <- '=='               skip
EQUALRARROW          <- '=>'               skip
EXCLAMATIONMARK      <- '!'      ![=]      skip
EXCLAMATIONMARKEQUAL <- '!='               skip
LARROW               <- '<'      ![<=]     skip
LARROW2              <- '<<'     ![=]      skip
LARROW2EQUAL         <- '<<='              skip
LARROWEQUAL          <- '<='               skip
LBRACE               <- '{'                skip
LBRACKET             <- '['                skip
LPAREN               <- '('                skip
MINUS                <- '-'      ![%=>]    skip
MINUSEQUAL           <- '-='               skip
MINUSPERCENT         <- '-%'     ![=]      skip
MINUSPERCENTEQUAL    <- '-%='              skip
MINUSRARROW          <- '->'               skip
PERCENT              <- '%'      ![=]      skip
PERCENTEQUAL         <- '%='               skip
PIPE                 <- '|'      ![|=]     skip
PIPE2                <- '||'               skip
PIPEEQUAL            <- '|='               skip
PLUS                 <- '+'      ![%+=]    skip
PLUS2                <- '++'               skip
PLUSEQUAL            <- '+='               skip
PLUSPERCENT          <- '+%'     ![=]      skip
PLUSPERCENTEQUAL     <- '+%='              skip
QUESTIONMARK         <- '?'                skip
RARROW               <- '>'      ![>=]     skip
RARROW2              <- '>>'     ![=]      skip
RARROW2EQUAL         <- '>>='              skip
RARROWEQUAL          <- '>='               skip
RBRACE               <- '}'                skip
RBRACKET             <- ']'                skip
RPAREN               <- ')'                skip
SEMICOLON            <- ';'                skip
SLASH                <- '/'      ![=]      skip
SLASHEQUAL           <- '/='               skip
TILDE                <- '~'                skip

end_of_word <- ![a-zA-Z0-9_] skip
KEYWORD_align       <- 'align'       end_of_word
KEYWORD_and         <- 'and'         end_of_word
KEYWORD_anyerror    <- 'anyerror'    end_of_word
KEYWORD_asm         <- 'asm'         end_of_word
KEYWORD_async       <- 'async'       end_of_word
KEYWORD_await       <- 'await'       end_of_word
KEYWORD_break       <- 'break'       end_of_word
KEYWORD_cancel      <- 'cancel'      end_of_word
KEYWORD_catch       <- 'catch'       end_of_word
KEYWORD_comptime    <- 'comptime'    end_of_word
KEYWORD_const       <- 'const'       end_of_word
KEYWORD_continue    <- 'continue'    end_of_word
KEYWORD_defer       <- 'defer'       end_of_word
KEYWORD_else        <- 'else'        end_of_word
KEYWORD_enum        <- 'enum'        end_of_word
KEYWORD_errdefer    <- 'errdefer'    end_of_word
KEYWORD_error       <- 'error'       end_of_word
KEYWORD_export      <- 'export'      end_of_word
KEYWORD_extern      <- 'extern'      end_of_word
KEYWORD_false       <- 'false'       end_of_word
KEYWORD_fn          <- 'fn'          end_of_word
KEYWORD_for         <- 'for'         end_of_word
KEYWORD_if          <- 'if'          end_of_word
KEYWORD_inline      <- 'inline'      end_of_word
KEYWORD_nakedcc     <- 'nakedcc'     end_of_word
KEYWORD_noalias     <- 'noalias'     end_of_word
KEYWORD_null        <- 'null'        end_of_word
KEYWORD_or          <- 'or'          end_of_word
KEYWORD_orelse      <- 'orelse'      end_of_word
KEYWORD_packed      <- 'packed'      end_of_word
KEYWORD_promise     <- 'promise'     end_of_word
KEYWORD_pub         <- 'pub'         end_of_word
KEYWORD_resume      <- 'resume'      end_of_word
KEYWORD_return      <- 'return'      end_of_word
KEYWORD_linksection <- 'linksection' end_of_word
KEYWORD_stdcallcc   <- 'stdcallcc'   end_of_word
KEYWORD_struct      <- 'struct'      end_of_word
KEYWORD_suspend     <- 'suspend'     end_of_word
KEYWORD_switch      <- 'switch'      end_of_word
KEYWORD_test        <- 'test'        end_of_word
KEYWORD_true        <- 'true'        end_of_word
KEYWORD_try         <- 'try'         end_of_word
KEYWORD_undefined   <- 'undefined'   end_of_word
KEYWORD_union       <- 'union'       end_of_word
KEYWORD_unreachable <- 'unreachable' end_of_word
KEYWORD_use         <- 'use'         end_of_word
KEYWORD_var         <- 'var'         end_of_word
KEYWORD_volatile    <- 'volatile'    end_of_word
KEYWORD_while       <- 'while'       end_of_word

keyword <- KEYWORD_align / KEYWORD_and / KEYWORD_anyerror / KEYWORD_asm
         / KEYWORD_async / KEYWORD_await / KEYWORD_break / KEYWORD_cancel
         / KEYWORD_catch / KEYWORD_comptime / KEYWORD_const / KEYWORD_continue
         / KEYWORD_defer / KEYWORD_else / KEYWORD_enum / KEYWORD_errdefer
         / KEYWORD_error / KEYWORD_export / KEYWORD_extern / KEYWORD_false
         / KEYWORD_fn / KEYWORD_for / KEYWORD_if / KEYWORD_inline
         / KEYWORD_nakedcc / KEYWORD_noalias / KEYWORD_null / KEYWORD_or
         / KEYWORD_orelse / KEYWORD_packed / KEYWORD_promise / KEYWORD_pub
         / KEYWORD_resume / KEYWORD_return / KEYWORD_linksection
         / KEYWORD_stdcallcc / KEYWORD_struct / KEYWORD_suspend
         / KEYWORD_switch / KEYWORD_test / KEYWORD_true / KEYWORD_try
         / KEYWORD_undefined / KEYWORD_union / KEYWORD_unreachable
         / KEYWORD_use / KEYWORD_var / KEYWORD_volatile / KEYWORD_while

• Communicate intent precisely.
• Edge cases matter.
• Favor reading code over writing code.
• Only one obvious way to do things.
• Runtime crashes are better than bugs.
• Compile errors are better than runtime crashes.
• Incremental improvements.
• Avoid local maximums.
• Reduce the amount one must remember.
• Minimize energy spent on coding style.
• Together we serve end users.