In this example the variable c_string_literal has type &const char and has a terminating null byte.

Use const to assign a value to an identifier:

If you need a variable that you can modify, use var:

Variables must be initialized:

Use undefined to leave variables uninitialized:

Integer literals have no size limitation, and if any undefined behavior occurs, the compiler catches it.

However, once an integer value is no longer known at compile-time, it must have a known size, and is vulnerable to undefined behavior.

In this function, values a and b are known only at runtime, and thus this division operation is vulnerable to both integer overflow and division by zero.

Operators such as + and - cause undefined behavior on integer overflow. Also available are operations such as +% and -% which are defined to have wrapping arithmetic on all targets.

By default floating point operations use Optimized mode, but you can switch to Strict mode on a per-block basis:

For this test we have to separate code into two object files - otherwise the optimizer figures out all the values at compile-time, which operates in strict mode.

a + b
a += b

2 + 5 == 7

a +% b
a +%= b

u32(@maxValue(u32)) +% 1 == 0

a - b
a -= b

2 - 5 == -3

a -% b
a -%= b

u32(0) -% 1 == @maxValue(u32)

-a

-1 == 0 - 1

-%a

-%i32(@minValue(i32)) == @minValue(i32)

a * b
a *= b

2 * 5 == 10

a *% b
a *%= b

u8(200) *% 2 == 144

a / b
a /= b

10 / 5 == 2

a % b
a %= b

10 % 3 == 1

a << b
a <<= b

1 << 8 == 256

a >> b
a >>= b

10 >> 1 == 5

a & b
a &= b

0b011 & 0b101 == 0b001

a | b
a |= b

0b010 | 0b100 == 0b110

a ^ b
a ^= b

0b011 ^ 0b101 == 0b110

~a

~u8(0b0101111) == 0b1010000

a ?? b

const value: ?u32 = null;
const unwrapped = value ?? 1234;
unwrapped == 1234

??a

a ?? unreachable

const value: ?u32 = 5678;
??value == 5678

a catch b
a catch |err| b

const value: %u32 = null;
const unwrapped = value catch 1234;
unwrapped == 1234

a and b

false and true == false

a or b

false or true == true

!a

!false == true

a == b

(1 == 1) == true

a == null

const value: ?u32 = null;
value == null

a != b

(1 != 1) == false

a > b

(2 > 1) == true

a >= b

(2 >= 1) == true

a < b

(1 < 2) == true

a <= b

(1 <= 2) == true

a ++ b

const mem = @import("std").mem;
const array1 = []u32{1,2};
const array2 = []u32{3,4};
const together = array1 ++ array2;
mem.eql(u32, together, []u32{1,2,3,4})

a ** b

const mem = @import("std").mem;
const pattern = "ab" ** 3;
mem.eql(u8, pattern, "ababab")

*a

const x: u32 = 1234;
const ptr = &x;
*x == 1234

&a

const x: u32 = 1234;
const ptr = &x;
*x == 1234

x() x[] x.y
!x -x -%x ~x *x &x ?x %x ??x
x{}
* / % ** *%
+ - ++ +% -%
<< >>
&
^
|
== != < > <= >=
and
or
?? catch
= *= /= %= += -= <<= >>= &= ^= |=

Each type has an alignment - a number of bytes such that, when a value of the type is loaded from or stored to memory, the memory address must be evenly divisible by this number. You can use @alignOf to find out this value for any type.

Alignment depends on the CPU architecture, but is always a power of two, and less than 1 << 29.

In Zig, a pointer type has an alignment value. If the value is equal to the alignment of the underlying type, it can be omitted from the type:

In the same way that a &i32 can be implicitly cast to a &const i32, a pointer with a larger alignment can be implicitly cast to a pointer with a smaller alignment, but not vice versa.

You can specify alignment on variables and functions. If you do this, then pointers to them get the specified alignment:

If you have a pointer or a slice that has a small alignment, but you know that it actually has a bigger alignment, use @alignCast to change the pointer into a more aligned pointer. This is a no-op at runtime, but inserts a safety check:

Zig uses Type Based Alias Analysis (also known as Strict Aliasing) to perform some optimizations. This means that pointers of different types must not alias the same memory, with the exception of u8. Pointers to u8 can alias any memory.

As an example, this code produces undefined behavior:

*@ptrCast(&u32, f32(12.34))

Instead, use @bitCast:

@bitCast(u32, f32(12.34))

As an added benefit, the @bitcast version works at compile-time.

This is one reason we prefer slices to pointers.

By default, enums are not guaranteed to be compatible with the C ABI:

For a C-ABI-compatible enum, use extern enum:

TODO packed enum

Unions with an enum tag are generated as a struct with a tag field and union field. Zig sorts the order of the tag and union field by the largest alignment.

In Debug and ReleaseSafe mode, and when using zig test, unreachable emits a call to panic with the message reached unreachable code.

In ReleaseFast mode, the optimizer uses the assumption that unreachable code will never be hit to perform optimizations. However, zig test even in ReleaseFast mode still emits unreachable as calls to panic.

In fact, this is how assert is implemented:

noreturn is the type of:

• break
• continue
• goto
• return
• unreachable
• while (true) {}

When resolving types together, such as if clauses or switch prongs, the noreturn type is compatible with every other type. Consider:

Another use case for noreturn is the exit function:

Function values are like pointers:

In Zig, structs, unions, and enums with payloads cannot be passed by value to a function.

Instead, one must use &const. Zig allows implicitly casting something to a const pointer to it:

However, the C ABI does allow passing structs and unions by value. So functions which use the C calling convention may pass structs and unions by value.

One of the distinguishing features of Zig is its exception handling strategy.

Among the top level declarations available is the error value declaration:

These error values are assigned an unsigned integer value greater than 0 at compile time. You are allowed to declare the same error value more than once, and if you do, it gets assigned the same integer value.

You can refer to these error values with the error namespace such as error.FileNotFound.

Each error value across the entire compilation unit gets a unique integer, and this determines the size of the pure error type.

The pure error type is one of the error values, and in the same way that pointers cannot be null, a pure error is always an error.

Most of the time you will not find yourself using a pure error type. Instead, likely you will be using the error union type. This is when you take a normal type, and prefix it with the % operator.

Here is a function to parse a string into a 64-bit integer:

Notice the return type is %u64. This means that the function either returns an unsigned 64 bit integer, or an error.

Within the function definition, you can see some return statements that return a pure error, and at the bottom a return statement that returns a u64. Both types implicitly cast to %u64.

What it looks like to use this function varies depending on what you're trying to do. One of the following:

• You want to provide a default value if it returned an error.
• If it returned an error then you want to return the same error.
• You know with complete certainty it will not return an error, so want to unconditionally unwrap it.
• You want to take a different action for each possible error.

If you want to provide a default value, you can use the catch binary operator:

In this code, number will be equal to the successfully parsed string, or a default value of 13. The type of the right hand side of the binary catch operator must match the unwrapped error union type, or be of type noreturn.

Let's say you wanted to return the error if you got one, otherwise continue with the function logic:

There is a shortcut for this. The try expression:

try evaluates an error union expression. If it is an error, it returns from the current function with the same error. Otherwise, the expression results in the unwrapped value.

Maybe you know with complete certainty that an expression will never be an error. In this case you can do this:

Here we know for sure that "1234" will parse successfully. So we put the unreachable value on the right hand side. unreachable generates a panic in Debug and ReleaseSafe modes and undefined behavior in ReleaseFast mode. So, while we're debugging the application, if there was a surprise error here, the application would crash appropriately. TODO: mention error return traces

Finally, you may want to take a different action for every situation. For that, we combine the if and switch expression:

The other component to error handling is defer statements. In addition to an unconditional defer, Zig has %defer, which evaluates the deferred expression on block exit path if and only if the function returned with an error from the block.

Example:

The neat thing about this is that you get robust error handling without the verbosity and cognitive overhead of trying to make sure every exit path is covered. The deallocation code is always directly following the allocation code.

A couple of other tidbits about error handling:

• These primitives give enough expressiveness that it's completely practical to have failing to check for an error be a compile error. If you really want to ignore the error, you can add catch unreachable and get the added benefit of crashing in Debug and ReleaseSafe modes if your assumption was wrong.
• Since Zig understands error types, it can pre-weight branches in favor of errors not occuring. Just a small optimization benefit that is not available in other languages.

One area that Zig provides safety without compromising efficiency or readability is with the nullable type.

The question mark symbolizes the nullable type. You can convert a type to a nullable type by putting a question mark in front of it, like this:

Now the variable nullable_int could be an i32, or null.

Instead of integers, let's talk about pointers. Null references are the source of many runtime exceptions, and even stand accused of being the worst mistake of computer science.

Zig does not have them.

Instead, you can use a nullable pointer. This secretly compiles down to a normal pointer, since we know we can use 0 as the null value for the nullable type. But the compiler can check your work and make sure you don't assign null to something that can't be null.

Typically the downside of not having null is that it makes the code more verbose to write. But, let's compare some equivalent C code and Zig code.

Task: call malloc, if the result is null, return null.

C code

// malloc prototype included for reference
void *malloc(size_t size);

struct Foo *do_a_thing(void) {
    char *ptr = malloc(1234);
    if (!ptr) return NULL;
    // ...
}

Zig code

Here, Zig is at least as convenient, if not more, than C. And, the type of "ptr" is &u8 not ?&u8. The ?? operator unwrapped the nullable type and therefore ptr is guaranteed to be non-null everywhere it is used in the function.

The other form of checking against NULL you might see looks like this:

void do_a_thing(struct Foo *foo) {
    // do some stuff

    if (foo) {
        do_something_with_foo(foo);
    }

    // do some stuff
}

In Zig you can accomplish the same thing:

Once again, the notable thing here is that inside the if block, foo is no longer a nullable pointer, it is a pointer, which cannot be null.

One benefit to this is that functions which take pointers as arguments can be annotated with the "nonnull" attribute - __attribute__((nonnull)) in GCC. The optimizer can sometimes make better decisions knowing that pointer arguments cannot be null.

TODO: explain implicit vs explicit casting

TODO: resolve peer types builtin

TODO: truncate builtin

TODO: bitcast builtin

TODO: int to ptr builtin

TODO: ptr to int builtin

TODO: ptrcast builtin

TODO: explain number literals vs concrete types

TODO: assigning void has no codegen

TODO: hashmap with void becomes a set

TODO: difference between c_void and void

TODO: void is the default return value of functions

TODO: functions require assigning the return value

TODO: example of this referring to Self struct

TODO: example of this referring to recursion function

TODO: example of this referring to basic block for @setDebugSafety

Zig places importance on the concept of whether an expression is known at compile-time. There are a few different places this concept is used, and these building blocks are used to keep the language small, readable, and powerful.

Compile-time parameters is how Zig implements generics. It is compile-time duck typing.

In Zig, types are first-class citizens. They can be assigned to variables, passed as parameters to functions, and returned from functions. However, they can only be used in expressions which are known at compile-time, which is why the parameter T in the above snippet must be marked with comptime.

A comptime parameter means that:

• At the callsite, the value must be known at compile-time, or it is a compile error.
• In the function definition, the value is known at compile-time.

For example, if we were to introduce another function to the above snippet:

This is an error because the programmer attempted to pass a value only known at run-time to a function which expects a value known at compile-time.

Another way to get an error is if we pass a type that violates the type checker when the function is analyzed. This is what it means to have compile-time duck typing.

For example:

On the flip side, inside the function definition with the comptime parameter, the value is known at compile-time. This means that we actually could make this work for the bool type if we wanted to:

This works because Zig implicitly inlines if expressions when the condition is known at compile-time, and the compiler guarantees that it will skip analysis of the branch not taken.

This means that the actual function generated for max in this situation looks like this:

All the code that dealt with compile-time known values is eliminated and we are left with only the necessary run-time code to accomplish the task.

This works the same way for switch expressions - they are implicitly inlined when the target expression is compile-time known.

In Zig, the programmer can label variables as comptime. This guarantees to the compiler that every load and store of the variable is performed at compile-time. Any violation of this results in a compile error.

This combined with the fact that we can inline loops allows us to write a function which is partially evaluated at compile-time and partially at run-time.

For example:

This example is a bit contrived, because the compile-time evaluation component is unnecessary; this code would work fine if it was all done at run-time. But it does end up generating different code. In this example, the function performFn is generated three different times, for the different values of prefix_char provided:

Note that this happens even in a debug build; in a release build these generated functions still pass through rigorous LLVM optimizations. The important thing to note, however, is not that this is a way to write more optimized code, but that it is a way to make sure that what should happen at compile-time, does happen at compile-time. This catches more errors and as demonstrated later in this article, allows expressiveness that in other languages requires using macros, generated code, or a preprocessor to accomplish.

In Zig, it matters whether a given expression is known at compile-time or run-time. A programmer can use a comptime expression to guarantee that the expression will be evaluated at compile-time. If this cannot be accomplished, the compiler will emit an error. For example:

It doesn't make sense that a program could call exit() (or any other external function) at compile-time, so this is a compile error. However, a comptime expression does much more than sometimes cause a compile error.

Within a comptime expression:

• All variables are comptime variables.
• All if, while, for, switch, and goto expressions are evaluated at compile-time, or emit a compile error if this is not possible.
• All function calls cause the compiler to interpret the function at compile-time, emitting a compile error if the function tries to do something that has global run-time side effects.

This means that a programmer can create a function which is called both at compile-time and run-time, with no modification to the function required.

Let's look at an example:

Imagine if we had forgotten the base case of the recursive function and tried to run the tests:

The compiler produces an error which is a stack trace from trying to evaluate the function at compile-time.

Luckily, we used an unsigned integer, and so when we tried to subtract 1 from 0, it triggered undefined behavior, which is always a compile error if the compiler knows it happened. But what would have happened if we used a signed integer?

The compiler noticed that evaluating this function at compile-time took a long time, and thus emitted a compile error and gave up. If the programmer wants to increase the budget for compile-time computation, they can use a built-in function called @setEvalBranchQuota to change the default number 1000 to something else.

What if we fix the base case, but put the wrong value in the assert line?

What happened is Zig started interpreting the assert function with the parameter ok set to false. When the interpreter hit unreachable it emitted a compile error, because reaching unreachable code is undefined behavior, and undefined behavior causes a compile error if it is detected at compile-time.

In the global scope (outside of any function), all expressions are implicitly comptime expressions. This means that we can use functions to initialize complex static data. For example:

When we compile this program, Zig generates the constants with the answer pre-computed. Here are the lines from the generated LLVM IR:

@0 = internal unnamed_addr constant [25 x i32] [i32 2, i32 3, i32 5, i32 7, i32 11, i32 13, i32 17, i32 19, i32 23, i32 29, i32 31, i32 37, i32 41, i32 43, i32 47, i32 53, i32 59, i32 61, i32 67, i32 71, i32 73, i32 79, i32 83, i32 89, i32 97]
@1 = internal unnamed_addr constant i32 1060

Note that we did not have to do anything special with the syntax of these functions. For example, we could call the sum function as is with a slice of numbers whose length and values were only known at run-time.

Zig uses these capabilities to implement generic data structures without introducing any special-case syntax. If you followed along so far, you may already know how to create a generic data structure.

Here is an example of a generic List data structure, that we will instantiate with the type i32. In Zig we refer to the type as List(i32).

That's it. It's a function that returns an anonymous struct. For the purposes of error messages and debugging, Zig infers the name "List(i32)" from the function name and parameters invoked when creating the anonymous struct.

To keep the language small and uniform, all aggregate types in Zig are anonymous. To give a type a name, we assign it to a constant:

This works because all top level declarations are order-independent, and as long as there isn't an actual infinite regression, values can refer to themselves, directly or indirectly. In this case, Node refers to itself as a pointer, which is not actually an infinite regression, so it works fine.

Putting all of this together, let's see how printf works in Zig.

Let's crack open the implementation of this and see how it works:

This is a proof of concept implementation; the actual function in the standard library has more formatting capabilities.

Note that this is not hard-coded into the Zig compiler; this is userland code in the standard library.

When this function is analyzed from our example code above, Zig partially evaluates the function and emits a function that actually looks like this:

printValue is a function that takes a parameter of any type, and does different things depending on the type:

And now, what happens if we give too many arguments to printf?

Zig gives programmers the tools needed to protect themselves against their own mistakes.

Zig doesn't care whether the format argument is a string literal, only that it is a compile-time known value that is implicitly castable to a []const u8:

This works fine.

Zig does not special case string formatting in the compiler and instead exposes enough power to accomplish this task in userland. It does so without introducing another language on top of Zig, such as a macro language or a preprocessor language. It's Zig all the way down.

TODO: suggestion to not use inline unless necessary

TODO: inline while

TODO: inline for

TODO: suggestion to not use inline unless necessary

TODO: example of inline assembly

TODO: example of module level assembly

TODO: example of using inline assembly return value

TODO: example of using inline assembly assigning values to variables

TODO: @fence()

TODO: @atomic rmw

TODO: builtin atomic memory ordering enum

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

@addWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool

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.

TODO

@bitCast(comptime DestType: type, value: var) -> DestType

Converts a value of one type to another type.

Asserts that @sizeOf(@typeOf(value)) == @sizeOf(DestType).

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

Can be used for these things for example:

• Convert f32 to u32 bits
• Convert i32 to u32 preserving twos complement

Works at compile-time if value 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.

@breakpoint()

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

This function is only valid within function scope.

@alignCast(comptime alignment: u29, ptr: var) -> var

ptr can be &T, fn(), ?&T, ?fn(), or []T. It returns the same type as ptr except with the alignment adjusted to the new value.

A pointer alignment safety check is added to the generated code to make sure the pointer is aligned as promised.

@alignOf(comptime T: type) -> (number literal)

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.

const assert = @import("std").debug.assert;
comptime {
    assert(&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).

@cDefine(comptime name: []u8, value)

This function can only occur inside @cImport.

This appends #define $name $value to the @cImport temporary buffer.

To define without a value, like this:

#define _GNU_SOURCE

Use the void value, like this:

@cDefine("_GNU_SOURCE", {})

@cImport(expression) -> (namespace)

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

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.

@cInclude(comptime path: []u8)

This function can only occur inside @cImport.

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

@cUndef(comptime name: []u8)

This function can only occur inside @cImport.

This appends #undef $name to the @cImport temporary buffer.

@canImplicitCast(comptime T: type, value) -> bool

Returns whether a value can be implicitly casted to a given type.

@clz(x: T) -> U

This function counts the number of leading zeroes in x which is an integer type T.

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

If x is zero, @clz returns T.bit_count.

@cmpxchg(ptr: &T, cmp: T, new: T, success_order: AtomicOrder, fail_order: AtomicOrder) -> bool

This function performs an atomic compare exchange operation.

AtomicOrder can be found with @import("builtin").AtomicOrder.

@typeOf(ptr).alignment must be >= @sizeOf(T).

@compileError(comptime msg: []u8)

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.

@compileLog(args: ...)

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 @compileLog calls are removed or not encountered by analysis, the program compiles successfully and the generated executable prints:

@ctz(x: T) -> U

This function counts the number of trailing zeroes in x which is an integer type T.

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

If x is zero, @ctz returns T.bit_count.

@divExact(numerator: T, denominator: T) -> T

Exact division. Caller guarantees denominator != 0 and @divTrunc(numerator, denominator) * denominator == numerator.

• @divExact(6, 3) == 2
• @divExact(a, b) * b == a

For a function that returns a possible error code, use @import("std").math.divExact.

@divFloor(numerator: T, denominator: T) -> T

Floored division. Rounds toward negative infinity. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeId(T) == builtin.TypeId.Int and T.is_signed and numerator == @minValue(T) and denominator == -1).

• @divFloor(-5, 3) == -2
• @divFloor(a, b) + @mod(a, b) == a

For a function that returns a possible error code, use @import("std").math.divFloor.

@divTrunc(numerator: T, denominator: T) -> T

Truncated division. Rounds toward zero. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeId(T) == builtin.TypeId.Int and T.is_signed and numerator == @minValue(T) and denominator == -1).

• @divTrunc(-5, 3) == -1
• @divTrunc(a, b) + @rem(a, b) == a

For a function that returns a possible error code, use @import("std").math.divTrunc.

@embedFile(comptime path: []const u8) -> [X]u8

This function returns a compile time constant 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.

path is absolute or relative to the current file, just like @import.

@export(comptime name: []const u8, target: var, linkage: builtin.GlobalLinkage) -> []const u8

Creates a symbol in the output object file.

@tagName(value: var) -> []const u8

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

@TagType(T: type) -> type

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.

@errorName(err: error) -> []u8

This function returns the string representation of an error. If an error declaration is:

error OutOfMem

Then the string representation 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.

@errorReturnTrace() -> ?&builtin.StackTrace

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

@fence(order: AtomicOrder)

The fence function is used to introduce happens-before edges between operations.

AtomicOrder can be found with @import("builtin").AtomicOrder.

@fieldParentPtr(comptime ParentType: type, comptime field_name: []const u8,
    field_ptr: &T) -> &ParentType

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

@frameAddress()

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.

@import(comptime path: []u8) -> (namespace)

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

path 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 @import function call.

The following packages are always available:

• @import("std") - Zig Standard Library
• @import("builtin") - Compiler-provided types and variables

@inlineCall(function: X, args: ...) -> Y

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

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

@intToPtr(comptime DestType: type, int: usize) -> DestType

Converts an integer to a pointer. To convert the other way, use @ptrToInt.

@IntType(comptime is_signed: bool, comptime bit_count: u8) -> type

This function returns an integer type with the given signness and bit count.

@maxValue(comptime T: type) -> (number literal)

This function returns the maximum value of the integer type T.

The result is a compile time constant.

@memberCount(comptime T: type) -> (number literal)

This function returns the number of enum values in an enum type.

The result is a compile time constant.

TODO

TODO

@memcpy(noalias dest: &u8, noalias source: &const u8, byte_count: usize)

This function copies bytes from one region of memory to another. dest and source 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:

for (source[0...byte_count]) |b, i| dest[i] = b;

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

There is also a standard library function for this:

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

@memset(dest: &u8, c: u8, byte_count: usize)

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:

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:

const mem = @import("std").mem;
mem.set(u8, dest, c);

@minValue(comptime T: type) -> (number literal)

This function returns the minimum value of the integer type T.

The result is a compile time constant.

@mod(numerator: T, denominator: T) -> T

Modulus division. For unsigned integers this is the same as numerator % denominator. Caller guarantees denominator > 0.

• @mod(-5, 3) == 1
• @divFloor(a, b) + @mod(a, b) == a

For a function that returns an error code, see @import("std").math.mod.

@mulWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool

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.

@noInlineCall(function: var, args: ...) -> var

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

const assert = @import("std").debug.assert;
test "noinline function call" {
    assert(@noInlineCall(add, 3, 9) == 12);
}

fn add(a: i32, b: i32) -> i32 { a + b }

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

@offsetOf(comptime T: type, comptime field_name: [] const u8) -> (number literal)

This function returns the byte offset of a field relative to its containing struct.

@OpaqueType() -> type

Creates a new type with an unknown size and alignment.

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

@panic(message: []const u8) -> noreturn

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, invokes the one provided in std/special/panic.zig.

Generally it is better to use @import("std").debug.panic. However, @panic 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.

@ptrCast(comptime DestType: type, value: var) -> DestType

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

@ptrToInt(value: var) -> usize

Converts value to a usize which is the address of the pointer. value can be one of these types:

• &T
• ?&T
• fn()
• ?fn()

To convert the other way, use @intToPtr

@rem(numerator: T, denominator: T) -> T

Remainder division. For unsigned integers this is the same as numerator % denominator. Caller guarantees denominator > 0.

• @rem(-5, 3) == -2
• @divTrunc(a, b) + @rem(a, b) == a

For a function that returns an error code, see @import("std").math.rem.

@returnAddress()

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.

@setCold(is_cold: bool)

Tells the optimizer that a function is rarely called.

@setDebugSafety(scope, safety_on: bool)

Sets whether debug safety checks are on for a given scope.

@setEvalBranchQuota(new_quota: usize)

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

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

Example:

Now we use @setEvalBranchQuota:

@setFloatMode(scope, mode: @import("builtin").FloatMode)

Sets the floating point mode for a given scope. Possible values are:

• Optimized (default) - 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.
• Strict - Floating point operations follow strict IEEE compliance.

@setGlobalLinkage(global_variable_name, comptime linkage: GlobalLinkage)

GlobalLinkage can be found with @import("builtin").GlobalLinkage.

@setGlobalSection(global_variable_name, comptime section_name: []const u8) -> bool

Puts the global variable in the specified section.

@shlExact(value: T, shift_amt: Log2T) -> T

Performs the left shift operation (<<). Caller guarantees that the shift will not shift any 1 bits out.

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.

@shlWithOverflow(comptime T: type, a: T, shift_amt: Log2T, result: &T) -> bool

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.

@shrExact(value: T, shift_amt: Log2T) -> T

Performs the right shift operation (>>). Caller guarantees that the shift will not shift any 1 bits out.

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.

@sizeOf(comptime T: type) -> (number literal)

This function returns the number of bytes it takes to store T in memory.

The result is a target-specific compile time constant.

@subWithOverflow(comptime T: type, a: T, b: T, result: &T) -> bool

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.

@truncate(comptime T: type, integer) -> T

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:

const a: u16 = 0xabcd;
const b: u8 = u8(a);

However this is well defined and working code:

const a: u16 = 0xabcd;
const b: u8 = @truncate(u8, a);
// b is now 0xcd

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

@typeId(comptime T: type) -> @import("builtin").TypeId

Returns which kind of type something is. Possible values:

@typeName(T: type) -> []u8

This function returns the string representation of a type.

@typeOf(expression) -> type

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

Zig has three build modes:

• Debug (default)
• ReleaseFast
• ReleaseSafe

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

$ zig build-exe example.zig

• Fast compilation speed
• Safety checks enabled
• Slow runtime performance

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

• Fast runtime performance
• Safety checks disabled
• Slow compilation speed

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

• Medium runtime performance
• Safety checks enabled
• Slow compilation speed

Zig has many instances of undefined behavior. If undefined behavior is detected at compile-time, Zig emits an error. 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 @setDebugSafety. The 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 crashes with the message reached unreachable code and a stack trace.

At compile-time:

At runtime crashes with the message index out of bounds and a stack trace.

At compile-time:

At runtime crashes with the message attempt to cast negative value to unsigned integer and a stack trace.

If you are trying to obtain the maximum value of an unsigned integer, use @maxValue(T), where T is the integer type, such as u32.

At compile-time:

At runtime crashes with the message integer cast truncated bits and a stack trace.

If you are trying to truncate bits, use @truncate(T, value), where T is the integer type, such as u32, and value is the value you want to truncate.

The following operators can cause integer overflow:

• + (addition)
• - (subtraction)
• - (negation)
• * (multiplication)
• / (division)
• @divTrunc (division)
• @divFloor (division)
• @divExact (division)

Example with addition at compile-time:

At runtime crashes with the message integer overflow and a stack trace.

These functions provided by the standard library return possible errors.

• @import("std").math.add
• @import("std").math.sub
• @import("std").math.mul
• @import("std").math.divTrunc
• @import("std").math.divFloor
• @import("std").math.divExact
• @import("std").math.shl

Example of catching an overflow for addition:

These builtins return a bool of whether or not overflow occurred, as well as returning the overflowed bits:

• @addWithOverflow
• @subWithOverflow
• @mulWithOverflow
• @shlWithOverflow

Example of @addWithOverflow:

These operations have guaranteed wraparound semantics.

• +% (wraparound addition)
• -% (wraparound subtraction)
• -% (wraparound negation)
• *% (wraparound multiplication)

At compile-time:

At runtime crashes with the message left shift overflowed bits and a stack trace.

At compile-time:

At runtime crashes with the message right shift overflowed bits and a stack trace.

At compile-time:

At runtime crashes with the message division by zero and a stack trace.

At compile-time:

At runtime crashes with the message remainder division by zero and a stack trace.

TODO

TODO

At compile-time:

At runtime crashes with the message attempt to unwrap null and a stack trace.

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

At compile-time:

At runtime crashes with the message attempt to unwrap error: ErrorCode and a stack trace.

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

At compile-time:

At runtime crashes with the message invalid error code and a stack trace.

TODO

TODO

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 "builtin" 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 @import("builtin"):

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.

• c_short
• c_ushort
• c_int
• c_uint
• c_long
• c_ulong
• c_longlong
• c_ulonglong
• c_longdouble
• c_void

The @cImport builtin function can be used to directly import symbols from .h files:

The @cImport 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:

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

$ 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 (@import("std")) has architecture, environment, and operating sytsem abstractions, and thus takes additional work to support more platforms. It currently supports Linux x86_64. Not all standard library code requires operating system abstractions, however, so things such as generic data structures work an all above platforms.

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 abilty to put an extra comma at the end.
• Line length: aim for 100; use common sense.

Roughly speaking: camelCaseFunctionName, TitleCaseTypeName, snake_case_variable_name. More precisely:

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

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 ENOENT, follow the established convention.

See the Zig Standard Library for more examples.

Root = many(TopLevelItem) EOF

TopLevelItem = ErrorValueDecl | CompTimeExpression(Block) | TopLevelDecl | TestDecl

TestDecl = "test" String Block

TopLevelDecl = option("pub") (FnDef | ExternDecl | GlobalVarDecl | UseDecl)

ErrorValueDecl = "error" Symbol ";"

GlobalVarDecl = option("export") VariableDeclaration ";"

LocalVarDecl = option("comptime") VariableDeclaration

VariableDeclaration = ("var" | "const") Symbol option(":" TypeExpr) option("align" "(" Expression ")") option("section" "(" Expression ")") "=" Expression

ContainerMember = (ContainerField | FnDef | GlobalVarDecl)

ContainerField = Symbol option(":" PrefixOpExpression option("=" PrefixOpExpression ","

UseDecl = "use" Expression ";"

ExternDecl = "extern" option(String) (FnProto | VariableDeclaration) ";"

FnProto = option("nakedcc" | "stdcallcc" | "extern") "fn" option(Symbol) ParamDeclList option("align" "(" Expression ")") option("section" "(" Expression ")") option("->" TypeExpr)

FnDef = option("inline" | "export") FnProto Block

ParamDeclList = "(" list(ParamDecl, ",") ")"

ParamDecl = option("noalias" | "comptime") option(Symbol ":") (TypeExpr | "...")

Block = option(Symbol ":") "{" many(Statement) "}"

Statement = LocalVarDecl ";" | Defer(Block) | Defer(Expression) ";" | BlockExpression(Block) | Expression ";" | ";"

TypeExpr = PrefixOpExpression | "var"

BlockOrExpression = Block | Expression

Expression = TryExpression | ReturnExpression | BreakExpression | AssignmentExpression

AsmExpression = "asm" option("volatile") "(" String option(AsmOutput) ")"

AsmOutput = ":" list(AsmOutputItem, ",") option(AsmInput)

AsmInput = ":" list(AsmInputItem, ",") option(AsmClobbers)

AsmOutputItem = "[" Symbol "]" String "(" (Symbol | "->" TypeExpr) ")"

AsmInputItem = "[" Symbol "]" String "(" Expression ")"

AsmClobbers= ":" list(String, ",")

UnwrapExpression = BoolOrExpression (UnwrapNullable | UnwrapError) | BoolOrExpression

UnwrapNullable = "??" Expression

UnwrapError = "catch" option("|" Symbol "|") Expression

AssignmentExpression = UnwrapExpression AssignmentOperator UnwrapExpression | UnwrapExpression

AssignmentOperator = "=" | "*=" | "/=" | "%=" | "+=" | "-=" | "<<=" | ">>=" | "&=" | "^=" | "|=" | "*%=" | "+%=" | "-%="

BlockExpression(body) = Block | IfExpression(body) | IfErrorExpression(body) | TestExpression(body) | WhileExpression(body) | ForExpression(body) | SwitchExpression | CompTimeExpression(body)

CompTimeExpression(body) = "comptime" body

SwitchExpression = "switch" "(" Expression ")" "{" many(SwitchProng) "}"

SwitchProng = (list(SwitchItem, ",") | "else") "=>" option("|" option("*") Symbol "|") Expression ","

SwitchItem = Expression | (Expression "..." Expression)

ForExpression(body) = option(Symbol ":") option("inline") "for" "(" Expression ")" option("|" option("*") Symbol option("," Symbol) "|") body option("else" BlockExpression(body))

BoolOrExpression = BoolAndExpression "or" BoolOrExpression | BoolAndExpression

ReturnExpression = "return" option(Expression)

TryExpression = "try" Expression

BreakExpression = "break" option(":" Symbol) option(Expression)

Defer(body) = option("%") "defer" body

IfExpression(body) = "if" "(" Expression ")" body option("else" BlockExpression(body))

IfErrorExpression(body) = "if" "(" Expression ")" option("|" option("*") Symbol "|") body "else" "|" Symbol "|" BlockExpression(body)

TestExpression(body) = "if" "(" Expression ")" option("|" option("*") Symbol "|") body option("else" BlockExpression(body))

WhileExpression(body) = option(Symbol ":") option("inline") "while" "(" Expression ")" option("|" option("*") Symbol "|") option(":" "(" Expression ")") body option("else" option("|" Symbol "|") BlockExpression(body))

BoolAndExpression = ComparisonExpression "and" BoolAndExpression | ComparisonExpression

ComparisonExpression = BinaryOrExpression ComparisonOperator BinaryOrExpression | BinaryOrExpression

ComparisonOperator = "==" | "!=" | "<" | ">" | "<=" | ">="

BinaryOrExpression = BinaryXorExpression "|" BinaryOrExpression | BinaryXorExpression

BinaryXorExpression = BinaryAndExpression "^" BinaryXorExpression | BinaryAndExpression

BinaryAndExpression = BitShiftExpression "&" BinaryAndExpression | BitShiftExpression

BitShiftExpression = AdditionExpression BitShiftOperator BitShiftExpression | AdditionExpression

BitShiftOperator = "<<" | ">>" | "<<"

AdditionExpression = MultiplyExpression AdditionOperator AdditionExpression | MultiplyExpression

AdditionOperator = "+" | "-" | "++" | "+%" | "-%"

MultiplyExpression = CurlySuffixExpression MultiplyOperator MultiplyExpression | CurlySuffixExpression

CurlySuffixExpression = TypeExpr option(ContainerInitExpression)

MultiplyOperator = "*" | "/" | "%" | "**" | "*%"

PrefixOpExpression = PrefixOp PrefixOpExpression | SuffixOpExpression

SuffixOpExpression = PrimaryExpression option(FnCallExpression | ArrayAccessExpression | FieldAccessExpression | SliceExpression)

FieldAccessExpression = "." Symbol

FnCallExpression = "(" list(Expression, ",") ")"

ArrayAccessExpression = "[" Expression "]"

SliceExpression = "[" Expression ".." option(Expression) "]"

ContainerInitExpression = "{" ContainerInitBody "}"

ContainerInitBody = list(StructLiteralField, ",") | list(Expression, ",")

StructLiteralField = "." Symbol "=" Expression

PrefixOp = "!" | "-" | "~" | "*" | ("&" option("align" "(" Expression option(":" Integer ":" Integer) ")" ) option("const") option("volatile")) | "?" | "%" | "??" | "-%" | "try"

PrimaryExpression = Integer | Float | String | CharLiteral | KeywordLiteral | GroupedExpression | BlockExpression(BlockOrExpression) | Symbol | ("@" Symbol FnCallExpression) | ArrayType | FnProto | AsmExpression | ("error" "." Symbol) | ContainerDecl | ("continue" option(":" Symbol))

ArrayType : "[" option(Expression) "]" option("align" "(" Expression option(":" Integer ":" Integer) ")")) option("const") option("volatile") TypeExpr

GroupedExpression = "(" Expression ")"

KeywordLiteral = "true" | "false" | "null" | "undefined" | "error" | "this" | "unreachable"

ContainerDecl = option("extern" | "packed")
  ("struct" option(GroupedExpression) | "union" option("enum" option(GroupedExpression) | GroupedExpression) | ("enum" option(GroupedExpression)))
  "{" many(ContainerMember) "}"

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

TODO: document changes from a31b23c46ba2a8c28df01adc1aa0b4d878b9a5cf (compile time reflection additions)