Zig Language Reference

const std = @import("std");

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();
    try stdout.print("Hello, {s}!\n", .{"world"});
}

$ zig build-exe hello.zig

$ ./hello
Hello, world!

const print = @import("std").debug.print;

pub fn main() void {
    print("Hello, world!\n", .{});
}

$ zig build-exe hello_again.zig

$ ./hello_again
Hello, world!

const print = @import("std").debug.print;

pub fn main() void {
    // Comments in Zig start with "//" and end at the next LF byte (end of line).
    // The line below is a comment and won't be executed.

    //print("Hello?", .{});

    print("Hello, world!\n", .{}); // another comment
}

$ zig build-exe comments.zig

$ ./comments
Hello, world!

/// A structure for storing a timestamp, with nanosecond precision (this is a
/// multiline doc comment).
const Timestamp = struct {
    /// The number of seconds since the epoch (this is also a doc comment).
    seconds: i64,  // signed so we can represent pre-1970 (not a doc comment)
    /// The number of nanoseconds past the second (doc comment again).
    nanos: u32,

    /// Returns a `Timestamp` struct representing the Unix epoch; that is, the
    /// moment of 1970 Jan 1 00:00:00 UTC (this is a doc comment too).
    pub fn unixEpoch() Timestamp {
        return Timestamp{
            .seconds = 0,
            .nanos = 0,
        };
    }
};

//! This module provides functions for retrieving the current date and
//! time with varying degrees of precision and accuracy. It does not
//! depend on libc, but will use functions from it if available.

// Top-level declarations are order-independent:
const print = std.debug.print;
const std = @import("std");
const os = std.os;
const assert = std.debug.assert;

pub fn main() void {
    // integers
    const one_plus_one: i32 = 1 + 1;
    print("1 + 1 = {}\n", .{one_plus_one});

    // floats
    const seven_div_three: f32 = 7.0 / 3.0;
    print("7.0 / 3.0 = {}\n", .{seven_div_three});

    // boolean
    print("{}\n{}\n{}\n", .{
        true and false,
        true or false,
        !true,
    });

    // optional
    var optional_value: ?[]const u8 = null;
    assert(optional_value == null);

    print("\noptional 1\ntype: {s}\nvalue: {s}\n", .{
        @typeName(@TypeOf(optional_value)),
        optional_value,
    });

    optional_value = "hi";
    assert(optional_value != null);

    print("\noptional 2\ntype: {s}\nvalue: {s}\n", .{
        @typeName(@TypeOf(optional_value)),
        optional_value,
    });

    // error union
    var number_or_error: anyerror!i32 = error.ArgNotFound;

    print("\nerror union 1\ntype: {s}\nvalue: {}\n", .{
        @typeName(@TypeOf(number_or_error)),
        number_or_error,
    });

    number_or_error = 1234;

    print("\nerror union 2\ntype: {s}\nvalue: {}\n", .{
        @typeName(@TypeOf(number_or_error)),
        number_or_error,
    });
}

$ zig build-exe values.zig

$ ./values
1 + 1 = 2
7.0 / 3.0 = 2.33333325e+00
false
true
false

optional 1
type: ?[]const u8
value: null

optional 2
type: ?[]const u8
value: hi

error union 1
type: anyerror!i32
value: error.ArgNotFound

error union 2
type: anyerror!i32
value: 1234

const print = @import("std").debug.print;
const mem = @import("std").mem; // will be used to compare bytes

pub fn main() void {
    const bytes = "hello";
    print("{s}\n", .{@typeName(@TypeOf(bytes))});       // *const [5:0]u8
    print("{d}\n", .{bytes.len});                       // 5
    print("{c}\n", .{bytes[1]});                        // 'e'
    print("{d}\n", .{bytes[5]});                        // 0
    print("{}\n", .{'e' == '\x65'});                    // true
    print("{d}\n", .{'\u{1f4a9}'});                     // 128169
    print("{d}\n", .{'💯'});                            // 128175
    print("{}\n", .{mem.eql(u8, "hello", "h\x65llo")}); // true
    print("0x{x}\n", .{"\xff"[0]}); // non-UTF-8 strings are possible with \xNN notation.
    print("{u}\n", .{'⚡'});
}

$ zig build-exe string_literals.zig

$ ./string_literals
*const [5:0]u8
5
e
0
true
128169
128175
true
0xff
⚡

const hello_world_in_c =
    \\#include <stdio.h>
    \\
    \\int main(int argc, char **argv) {
    \\    printf("hello world\n");
    \\    return 0;
    \\}
;

const x = 1234;

fn foo() void {
    // It works at file scope as well as inside functions.
    const y = 5678;

    // Once assigned, an identifier cannot be changed.
    y += 1;
}

pub fn main() void {
    foo();
}

$ zig build-exe constant_identifier_cannot_change.zig
./docgen_tmp/constant_identifier_cannot_change.zig:8:7: error: cannot assign to constant
    y += 1;
      ^

const print = @import("std").debug.print;

pub fn main() void {
    var y: i32 = 5678;

    y += 1;

    print("{d}", .{y});
}

$ zig build-exe mutable_var.zig

$ ./mutable_var
5679

pub fn main() void {
    var x: i32;

    x = 1;
}

$ zig build-exe var_must_be_initialized.zig
docgen_tmp/var_must_be_initialized.zig:2:5: error: variables must be initialized
    var x: i32;
    ^

const print = @import("std").debug.print;

pub fn main() void {
    var x: i32 = undefined;
    x = 1;
    print("{d}", .{x});
}

$ zig build-exe assign_undefined.zig

$ ./assign_undefined
1

const std = @import("std");

test "expect addOne adds one to 41" {

    // The Standard Library contains useful functions to help create tests.
    // `expect` is a function that verifies its argument is true.
    // It will return an error if its argument is false to indicate a failure.
    // `try` is used to return an error to the test runner to notify it that the test failed.
    try std.testing.expect(addOne(41) == 42);
}

/// The function `addOne` adds one to the number given as its argument.
fn addOne(number: i32) i32 {
    return number + 1;
}

$ zig test introducing_zig_test.zig
1/1 test "expect addOne adds one to 41"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

// Imported source file tests will run when referenced from a top-level test declaration.
// The next line alone does not cause "introducing_zig_test.zig" tests to run.
const imported_file = @import("introducing_zig_test.zig");

test {
    // To run nested container tests, either, call `refAllDecls` which will
    // reference all declarations located in the given argument.
    // `@This()` is a builtin function that returns the innermost container it is called from.
    // In this example, the innermost container is this file (implicitly a struct).
    std.testing.refAllDecls(@This());

    // or, reference each container individually from a top-level test declaration.
    // The `_ = C;` syntax is a no-op reference to the identifier `C`.
    _ = S;
    _ = U;
    _ = @import("introducing_zig_test.zig");
}

const S = struct {
    test "S demo test" {
        try expect(true);
    }

    const SE = enum {
        V,

        // This test won't run because its container (SE) is not referenced.
        test "This Test Won't Run" {
            try expect(false);
        }
    };
};

const U = union { // U is referenced by the file's top-level test declaration
    s: US,        // and US is referenced here; therefore, "U.Us demo test" will run

    const US = struct {
        test "U.US demo test" {
            // This test is a top-level test declaration for the struct.
            // The struct is nested (declared) inside of a union.
            try expect(true);
        }
    };

    test "U demo test" {
        try expect(true);
    }
};

$ zig test testdecl_container_top_level.zig
1/5 test ""... OK
2/5 S.test "S demo test"... OK
3/5 U.test "U demo test"... OK
4/5 introducing_zig_test.test "expect addOne adds one to 41"... OK
5/5 US.test "U.US demo test"... OK
All 5 tests passed.

const std = @import("std");

test "expect this to fail" {
    try std.testing.expect(false);
}

test "expect this to succeed" {
    try std.testing.expect(true);
}

$ zig test test.zig
1/2 test "expect this to fail"... test "expect this to fail"... FAIL (TestUnexpectedResult)
FAIL (TestUnexpectedResult)
/home/andy/tmp/zig/lib/std/testing.zig:303:14: 0x207ebb in std.testing.expect (test)
    if (!ok) return error.TestUnexpectedResult;
             ^
/home/andy/tmp/zig/docgen_tmp/test.zig:4:5: 0x2078f1 in test "expect this to fail" (test)
    try std.testing.expect(false);
    ^
2/2 test "expect this to succeed"... OK
1 passed; 0 skipped; 1 failed.
error: the following test command failed with exit code 1:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

test "this will be skipped" {
    return error.SkipZigTest;
}

$ zig test test.zig
1/1 test "this will be skipped"... test "this will be skipped"... SKIP
SKIP
0 passed; 1 skipped; 0 failed.

const std = @import("std");

test "async skip test" {
    var frame = async func();
    const result = await frame;
    try std.testing.expect(result == 1);
}

fn func() i32 {
    suspend {
        resume @frame();
    }
    return 1;
}

$ zig test async_skip.zig
1/1 test "async skip test"... test "async skip test"... SKIP (async test)
SKIP (async test)
0 passed; 1 skipped; 0 failed.

const std = @import("std");

test "detect leak" {
    var list = std.ArrayList(u21).init(std.testing.allocator);
    // missing `defer list.deinit();`
    try list.append('☔');

    try std.testing.expect(list.items.len == 1);
}

$ zig test test.zig
1/1 test "detect leak"... OK
[gpa] (err): memory address 0x7ff65e3b1000 leaked:
/home/andy/tmp/zig/lib/std/array_list.zig:325:69: 0x20ce89 in std.array_list.ArrayListAligned(u21,null).ensureTotalCapacityPrecise (test)
                const new_memory = try self.allocator.reallocAtLeast(self.allocatedSlice(), new_capacity);
                                                                    ^
/home/andy/tmp/zig/lib/std/array_list.zig:310:55: 0x20cc8e in std.array_list.ArrayListAligned(u21,null).ensureTotalCapacity (test)
                return self.ensureTotalCapacityPrecise(better_capacity);
                                                      ^
/home/andy/tmp/zig/lib/std/array_list.zig:349:41: 0x20cc08 in std.array_list.ArrayListAligned(u21,null).addOne (test)
            try self.ensureTotalCapacity(newlen);
                                        ^
/home/andy/tmp/zig/lib/std/array_list.zig:161:49: 0x209204 in std.array_list.ArrayListAligned(u21,null).append (test)
            const new_item_ptr = try self.addOne();
                                                ^
/home/andy/tmp/zig/docgen_tmp/test.zig:6:20: 0x208be0 in test "detect leak" (test)
    try list.append('☔');
                   ^
/home/andy/tmp/zig/lib/std/special/test_runner.zig:80:28: 0x23b033 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/tmp/zig/lib/std/start.zig:551:22: 0x23390c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/tmp/zig/lib/std/start.zig:495:12: 0x20dc7e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^


All 1 tests passed.
1 errors were logged.
1 tests leaked memory.
error: the following test command failed with exit code 1:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;

test "builtin.is_test" {
    try expect(isATest());
}

fn isATest() bool {
    return builtin.is_test;
}

$ zig test detect_test.zig
1/1 test "builtin.is_test"... OK
All 1 tests passed.

const std = @import("std");

test "expectEqual demo" {
    const expected: i32 = 42;
    const actual = 42;

    // The first argument to `expectEqual` is the known, expected, result.
    // The second argument is the result of some expression.
    // The actual's type is casted to the type of expected.
    try std.testing.expectEqual(expected, actual);
}

test "expectError demo" {
    const expected_error = error.DemoError;
    const actual_error_union: anyerror!void = error.DemoError;

    // `expectError` will fail when the actual error is different than
    // the expected error.
    try std.testing.expectError(expected_error, actual_error_union);
}

$ zig test testing_functions.zig
1/2 test "expectEqual demo"... OK
2/2 test "expectError demo"... OK
All 2 tests passed.

const @"identifier with spaces in it" = 0xff;
const @"1SmallStep4Man" = 112358;

const c = @import("std").c;
pub extern "c" fn @"error"() anyopaque;
pub extern "c" fn @"fstat$INODE64"(fd: c.fd_t, buf: *c.Stat) c_int;

const Color = enum {
  red,
  @"really red",
};
const color: Color = .@"really red";

var y: i32 = add(10, x);
const x: i32 = add(12, 34);

test "container level variables" {
    try expect(x == 46);
    try expect(y == 56);
}

fn add(a: i32, b: i32) i32 {
    return a + b;
}

const std = @import("std");
const expect = std.testing.expect;

$ zig test container_level_variables.zig
1/1 test "container level variables"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "namespaced container level variable" {
    try expect(foo() == 1235);
    try expect(foo() == 1236);
}

const S = struct {
    var x: i32 = 1234;
};

fn foo() i32 {
    S.x += 1;
    return S.x;
}

$ zig test namespaced_container_level_variable.zig
1/1 test "namespaced container level variable"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "static local variable" {
    try expect(foo() == 1235);
    try expect(foo() == 1236);
}

fn foo() i32 {
    const S = struct {
        var x: i32 = 1234;
    };
    S.x += 1;
    return S.x;
}

$ zig test static_local_variable.zig
1/1 test "static local variable"... OK
All 1 tests passed.

const std = @import("std");
const assert = std.debug.assert;

threadlocal var x: i32 = 1234;

test "thread local storage" {
    const thread1 = try std.Thread.spawn(.{}, testTls, .{});
    const thread2 = try std.Thread.spawn(.{}, testTls, .{});
    testTls();
    thread1.join();
    thread2.join();
}

fn testTls() void {
    assert(x == 1234);
    x += 1;
    assert(x == 1235);
}

$ zig test tls.zig
1/1 test "thread local storage"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "comptime vars" {
    var x: i32 = 1;
    comptime var y: i32 = 1;

    x += 1;
    y += 1;

    try expect(x == 2);
    try expect(y == 2);

    if (y != 2) {
        // This compile error never triggers because y is a comptime variable,
        // and so `y != 2` is a comptime value, and this if is statically evaluated.
        @compileError("wrong y value");
    }
}

$ zig test comptime_vars.zig
1/1 test "comptime vars"... OK
All 1 tests passed.

const decimal_int = 98222;
const hex_int = 0xff;
const another_hex_int = 0xFF;
const octal_int = 0o755;
const binary_int = 0b11110000;

// underscores may be placed between two digits as a visual separator
const one_billion = 1_000_000_000;
const binary_mask = 0b1_1111_1111;
const permissions = 0o7_5_5;
const big_address = 0xFF80_0000_0000_0000;

fn divide(a: i32, b: i32) i32 {
    return a / b;
}

const floating_point = 123.0E+77;
const another_float = 123.0;
const yet_another = 123.0e+77;

const hex_floating_point = 0x103.70p-5;
const another_hex_float = 0x103.70;
const yet_another_hex_float = 0x103.70P-5;

// underscores may be placed between two digits as a visual separator
const lightspeed = 299_792_458.000_000;
const nanosecond = 0.000_000_001;
const more_hex = 0x1234_5678.9ABC_CDEFp-10;

const std = @import("std");

const inf = std.math.inf(f32);
const negative_inf = -std.math.inf(f64);
const nan = std.math.nan(f128);

const std = @import("std");
const big = @as(f64, 1 << 40);

export fn foo_strict(x: f64) f64 {
    return x + big - big;
}

export fn foo_optimized(x: f64) f64 {
    @setFloatMode(.Optimized);
    return x + big - big;
}

$ zig build-obj foo.zig -O ReleaseFast

const print = @import("std").debug.print;

extern fn foo_strict(x: f64) f64;
extern fn foo_optimized(x: f64) f64;

pub fn main() void {
    const x = 0.001;
    print("optimized = {}\n", .{foo_optimized(x)});
    print("strict = {}\n", .{foo_strict(x)});
}

$ zig build-exe float_mode.zig foo.o

$ ./float_mode
optimized = 1.0e-03
strict = 9.765625e-04

const expect = @import("std").testing.expect;
const assert = @import("std").debug.assert;
const mem = @import("std").mem;

// array literal
const message = [_]u8{ 'h', 'e', 'l', 'l', 'o' };

// get the size of an array
comptime {
    assert(message.len == 5);
}

// A string literal is a single-item pointer to an array literal.
const same_message = "hello";

comptime {
    assert(mem.eql(u8, &message, same_message));
}

test "iterate over an array" {
    var sum: usize = 0;
    for (message) |byte| {
        sum += byte;
    }
    try expect(sum == 'h' + 'e' + 'l' * 2 + 'o');
}

// modifiable array
var some_integers: [100]i32 = undefined;

test "modify an array" {
    for (some_integers) |*item, i| {
        item.* = @intCast(i32, i);
    }
    try expect(some_integers[10] == 10);
    try expect(some_integers[99] == 99);
}

// array concatenation works if the values are known
// at compile time
const part_one = [_]i32{ 1, 2, 3, 4 };
const part_two = [_]i32{ 5, 6, 7, 8 };
const all_of_it = part_one ++ part_two;
comptime {
    assert(mem.eql(i32, &all_of_it, &[_]i32{ 1, 2, 3, 4, 5, 6, 7, 8 }));
}

// remember that string literals are arrays
const hello = "hello";
const world = "world";
const hello_world = hello ++ " " ++ world;
comptime {
    assert(mem.eql(u8, hello_world, "hello world"));
}

// ** does repeating patterns
const pattern = "ab" ** 3;
comptime {
    assert(mem.eql(u8, pattern, "ababab"));
}

// initialize an array to zero
const all_zero = [_]u16{0} ** 10;

comptime {
    assert(all_zero.len == 10);
    assert(all_zero[5] == 0);
}

// use compile-time code to initialize an array
var fancy_array = init: {
    var initial_value: [10]Point = undefined;
    for (initial_value) |*pt, i| {
        pt.* = Point{
            .x = @intCast(i32, i),
            .y = @intCast(i32, i) * 2,
        };
    }
    break :init initial_value;
};
const Point = struct {
    x: i32,
    y: i32,
};

test "compile-time array initialization" {
    try expect(fancy_array[4].x == 4);
    try expect(fancy_array[4].y == 8);
}

// call a function to initialize an array
var more_points = [_]Point{makePoint(3)} ** 10;
fn makePoint(x: i32) Point {
    return Point{
        .x = x,
        .y = x * 2,
    };
}
test "array initialization with function calls" {
    try expect(more_points[4].x == 3);
    try expect(more_points[4].y == 6);
    try expect(more_points.len == 10);
}

$ zig test arrays.zig
1/4 test "iterate over an array"... OK
2/4 test "modify an array"... OK
3/4 test "compile-time array initialization"... OK
4/4 test "array initialization with function calls"... OK
All 4 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "anonymous list literal syntax" {
    var array: [4]u8 = .{11, 22, 33, 44};
    try expect(array[0] == 11);
    try expect(array[1] == 22);
    try expect(array[2] == 33);
    try expect(array[3] == 44);
}

$ zig test anon_list.zig
1/1 test "anonymous list literal syntax"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "fully anonymous list literal" {
    try dump(.{ @as(u32, 1234), @as(f64, 12.34), true, "hi"});
}

fn dump(args: anytype) !void {
    try expect(args.@"0" == 1234);
    try expect(args.@"1" == 12.34);
    try expect(args.@"2");
    try expect(args.@"3"[0] == 'h');
    try expect(args.@"3"[1] == 'i');
}

$ zig test infer_list_literal.zig
1/1 test "fully anonymous list literal"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const mat4x4 = [4][4]f32{
    [_]f32{ 1.0, 0.0, 0.0, 0.0 },
    [_]f32{ 0.0, 1.0, 0.0, 1.0 },
    [_]f32{ 0.0, 0.0, 1.0, 0.0 },
    [_]f32{ 0.0, 0.0, 0.0, 1.0 },
};
test "multidimensional arrays" {
    // Access the 2D array by indexing the outer array, and then the inner array.
    try expect(mat4x4[1][1] == 1.0);

    // Here we iterate with for loops.
    for (mat4x4) |row, row_index| {
        for (row) |cell, column_index| {
            if (row_index == column_index) {
                try expect(cell == 1.0);
            }
        }
    }
}

$ zig test multidimensional.zig
1/1 test "multidimensional arrays"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "null terminated array" {
    const array = [_:0]u8 {1, 2, 3, 4};

    try expect(@TypeOf(array) == [4:0]u8);
    try expect(array.len == 4);
    try expect(array[4] == 0);
}

$ zig test null_terminated_array.zig
1/1 test "null terminated array"... OK
All 1 tests passed.

const std = @import("std");
const Vector = std.meta.Vector;
const expectEqual = std.testing.expectEqual;

test "Basic vector usage" {
    // Vectors have a compile-time known length and base type,
    // and can be assigned to using array literal syntax
    const a: Vector(4, i32) = [_]i32{ 1, 2, 3, 4 };
    const b: Vector(4, i32) = [_]i32{ 5, 6, 7, 8 };

    // Math operations take place element-wise
    const c = a + b;

    // Individual vector elements can be accessed using array indexing syntax.
    try expectEqual(6, c[0]);
    try expectEqual(8, c[1]);
    try expectEqual(10, c[2]);
    try expectEqual(12, c[3]);
}

test "Conversion between vectors, arrays, and slices" {
    // Vectors and fixed-length arrays can be automatically assigned back and forth
    var arr1: [4]f32 = [_]f32{ 1.1, 3.2, 4.5, 5.6 };
    var vec: Vector(4, f32) = arr1;
    var arr2: [4]f32 = vec;
    try expectEqual(arr1, arr2);

    // You can also assign from a slice with comptime-known length to a vector using .*
    const vec2: Vector(2, f32) = arr1[1..3].*;

    var slice: []const f32 = &arr1;
    var offset: u32 = 1;
    // To extract a comptime-known length from a runtime-known offset,
    // first extract a new slice from the starting offset, then an array of
    // comptime known length
    const vec3: Vector(2, f32) = slice[offset..][0..2].*;
    try expectEqual(slice[offset], vec2[0]);
    try expectEqual(slice[offset + 1], vec2[1]);
    try expectEqual(vec2, vec3);
}

$ zig test vector_example.zig
1/2 test "Basic vector usage"... OK
2/2 test "Conversion between vectors, arrays, and slices"... OK
All 2 tests passed.

const expect = @import("std").testing.expect;

test "address of syntax" {
    // Get the address of a variable:
    const x: i32 = 1234;
    const x_ptr = &x;

    // Dereference a pointer:
    try expect(x_ptr.* == 1234);

    // When you get the address of a const variable, you get a const single-item pointer.
    try expect(@TypeOf(x_ptr) == *const i32);

    // If you want to mutate the value, you'd need an address of a mutable variable:
    var y: i32 = 5678;
    const y_ptr = &y;
    try expect(@TypeOf(y_ptr) == *i32);
    y_ptr.* += 1;
    try expect(y_ptr.* == 5679);
}

test "pointer array access" {
    // Taking an address of an individual element gives a
    // single-item pointer. This kind of pointer
    // does not support pointer arithmetic.
    var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
    const ptr = &array[2];
    try expect(@TypeOf(ptr) == *u8);

    try expect(array[2] == 3);
    ptr.* += 1;
    try expect(array[2] == 4);
}

$ zig test single_item_pointer_test.zig
1/2 test "address of syntax"... OK
2/2 test "pointer array access"... OK
All 2 tests passed.

const expect = @import("std").testing.expect;

test "pointer slicing" {
    var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
    const slice = array[2..4];
    try expect(slice.len == 2);

    try expect(array[3] == 4);
    slice[1] += 1;
    try expect(array[3] == 5);
}

$ zig test slice_bounds.zig
1/1 test "pointer slicing"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

test "comptime pointers" {
    comptime {
        var x: i32 = 1;
        const ptr = &x;
        ptr.* += 1;
        x += 1;
        try expect(ptr.* == 3);
    }
}

$ zig test comptime_pointers.zig
1/1 test "comptime pointers"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

test "@ptrToInt and @intToPtr" {
    const ptr = @intToPtr(*i32, 0xdeadbee0);
    const addr = @ptrToInt(ptr);
    try expect(@TypeOf(addr) == usize);
    try expect(addr == 0xdeadbee0);
}

$ zig test integer_pointer_conversion.zig
1/1 test "@ptrToInt and @intToPtr"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

test "comptime @intToPtr" {
    comptime {
        // Zig is able to do this at compile-time, as long as
        // ptr is never dereferenced.
        const ptr = @intToPtr(*i32, 0xdeadbee0);
        const addr = @ptrToInt(ptr);
        try expect(@TypeOf(addr) == usize);
        try expect(addr == 0xdeadbee0);
    }
}

$ zig test comptime_pointer_conversion.zig
1/1 test "comptime @intToPtr"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

test "volatile" {
    const mmio_ptr = @intToPtr(*volatile u8, 0x12345678);
    try expect(@TypeOf(mmio_ptr) == *volatile u8);
}

$ zig test volatile.zig
1/1 test "volatile"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "pointer casting" {
    const bytes align(@alignOf(u32)) = [_]u8{ 0x12, 0x12, 0x12, 0x12 };
    const u32_ptr = @ptrCast(*const u32, &bytes);
    try expect(u32_ptr.* == 0x12121212);

    // Even this example is contrived - there are better ways to do the above than
    // pointer casting. For example, using a slice narrowing cast:
    const u32_value = std.mem.bytesAsSlice(u32, bytes[0..])[0];
    try expect(u32_value == 0x12121212);

    // And even another way, the most straightforward way to do it:
    try expect(@bitCast(u32, bytes) == 0x12121212);
}

test "pointer child type" {
    // pointer types have a `child` field which tells you the type they point to.
    try expect(@typeInfo(*u32).Pointer.child == u32);
}

$ zig test pointer_casting.zig
1/2 test "pointer casting"... OK
2/2 test "pointer child type"... OK
All 2 tests passed.

const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;

test "variable alignment" {
    var x: i32 = 1234;
    const align_of_i32 = @alignOf(@TypeOf(x));
    try expect(@TypeOf(&x) == *i32);
    try expect(*i32 == *align(align_of_i32) i32);
    if (builtin.target.cpu.arch == .x86_64) {
        try expect(@typeInfo(*i32).Pointer.alignment == 4);
    }
}

$ zig test variable_alignment.zig
1/1 test "variable alignment"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

var foo: u8 align(4) = 100;

test "global variable alignment" {
    try expect(@typeInfo(@TypeOf(&foo)).Pointer.alignment == 4);
    try expect(@TypeOf(&foo) == *align(4) u8);
    const as_pointer_to_array: *[1]u8 = &foo;
    const as_slice: []u8 = as_pointer_to_array;
    try expect(@TypeOf(as_slice) == []align(4) u8);
}

fn derp() align(@sizeOf(usize) * 2) i32 { return 1234; }
fn noop1() align(1) void {}
fn noop4() align(4) void {}

test "function alignment" {
    try expect(derp() == 1234);
    try expect(@TypeOf(noop1) == fn() align(1) void);
    try expect(@TypeOf(noop4) == fn() align(4) void);
    noop1();
    noop4();
}

$ zig test variable_func_alignment.zig
1/2 test "global variable alignment"... OK
2/2 test "function alignment"... OK
All 2 tests passed.

const std = @import("std");

test "pointer alignment safety" {
    var array align(4) = [_]u32{ 0x11111111, 0x11111111 };
    const bytes = std.mem.sliceAsBytes(array[0..]);
    try std.testing.expect(foo(bytes) == 0x11111111);
}
fn foo(bytes: []u8) u32 {
    const slice4 = bytes[1..5];
    const int_slice = std.mem.bytesAsSlice(u32, @alignCast(4, slice4));
    return int_slice[0];
}

$ zig test test.zig
1/1 test "pointer alignment safety"... thread 1425104 panic: incorrect alignment
/home/andy/tmp/zig/docgen_tmp/test.zig:10:63: 0x207f8c in foo (test)
    const int_slice = std.mem.bytesAsSlice(u32, @alignCast(4, slice4));
                                                              ^
/home/andy/tmp/zig/docgen_tmp/test.zig:6:31: 0x207909 in test "pointer alignment safety" (test)
    try std.testing.expect(foo(bytes) == 0x11111111);
                              ^
/home/andy/tmp/zig/lib/std/special/test_runner.zig:80:28: 0x22f3d3 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/tmp/zig/lib/std/start.zig:551:22: 0x22874c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/tmp/zig/lib/std/start.zig:495:12: 0x2093de in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/tmp/zig/lib/std/start.zig:409:17: 0x2083e6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/tmp/zig/lib/std/start.zig:322:5: 0x2081f2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

const std = @import("std");
const expect = std.testing.expect;

test "allowzero" {
    var zero: usize = 0;
    var ptr = @intToPtr(*allowzero i32, zero);
    try expect(@ptrToInt(ptr) == 0);
}

$ zig test allowzero.zig
1/1 test "allowzero"... OK
All 1 tests passed.

const std = @import("std");

// This is also available as `std.c.printf`.
pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;

pub fn main() anyerror!void {
    _ = printf("Hello, world!\n"); // OK

    const msg = "Hello, world!\n";
    const non_null_terminated_msg: [msg.len]u8 = msg.*;
    _ = printf(&non_null_terminated_msg);
}

$ zig build-exe test.zig -lc
./docgen_tmp/test.zig:11:17: error: expected type '[*:0]const u8', found '*const [14]u8'
    _ = printf(&non_null_terminated_msg);
                ^
./docgen_tmp/test.zig:11:17: note: destination pointer requires a terminating '0' sentinel
    _ = printf(&non_null_terminated_msg);
                ^

const expect = @import("std").testing.expect;

test "basic slices" {
    var array = [_]i32{ 1, 2, 3, 4 };
    // A slice is a pointer and a length. The difference between an array and
    // a slice is that the array's length is part of the type and known at
    // compile-time, whereas the slice's length is known at runtime.
    // Both can be accessed with the `len` field.
    var known_at_runtime_zero: usize = 0;
    const slice = array[known_at_runtime_zero..array.len];
    try expect(&slice[0] == &array[0]);
    try expect(slice.len == array.len);

    // Using the address-of operator on a slice gives a single-item pointer,
    // while using the `ptr` field gives a many-item pointer.
    try expect(@TypeOf(slice.ptr) == [*]i32);
    try expect(@TypeOf(&slice[0]) == *i32);
    try expect(@ptrToInt(slice.ptr) == @ptrToInt(&slice[0]));

    // Slices have array bounds checking. If you try to access something out
    // of bounds, you'll get a safety check failure:
    slice[10] += 1;

    // Note that `slice.ptr` does not invoke safety checking, while `&slice[0]`
    // asserts that the slice has len >= 1.
}

$ zig test test.zig
1/1 test "basic slices"... thread 1425797 panic: index out of bounds
/home/andy/tmp/zig/docgen_tmp/test.zig:22:10: 0x207b23 in test "basic slices" (test)
    slice[10] += 1;
         ^
/home/andy/tmp/zig/lib/std/special/test_runner.zig:80:28: 0x22f3d3 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/tmp/zig/lib/std/start.zig:551:22: 0x22874c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/tmp/zig/lib/std/start.zig:495:12: 0x2093de in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/tmp/zig/lib/std/start.zig:409:17: 0x208476 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/tmp/zig/lib/std/start.zig:322:5: 0x208282 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

const std = @import("std");
const expect = std.testing.expect;
const mem = std.mem;
const fmt = std.fmt;

test "using slices for strings" {
    // Zig has no concept of strings. String literals are const pointers
    // to null-terminated arrays of u8, and by convention parameters
    // that are "strings" are expected to be UTF-8 encoded slices of u8.
    // Here we coerce *const [5:0]u8 and *const [6:0]u8 to []const u8
    const hello: []const u8 = "hello";
    const world: []const u8 = "世界";

    var all_together: [100]u8 = undefined;
    // You can use slice syntax on an array to convert an array into a slice.
    const all_together_slice = all_together[0..];
    // String concatenation example.
    const hello_world = try fmt.bufPrint(all_together_slice, "{s} {s}", .{ hello, world });

    // Generally, you can use UTF-8 and not worry about whether something is a
    // string. If you don't need to deal with individual characters, no need
    // to decode.
    try expect(mem.eql(u8, hello_world, "hello 世界"));
}

test "slice pointer" {
    var array: [10]u8 = undefined;
    const ptr = &array;

    // You can use slicing syntax to convert a pointer into a slice:
    const slice = ptr[0..5];
    slice[2] = 3;
    try expect(slice[2] == 3);
    // The slice is mutable because we sliced a mutable pointer.
    // Furthermore, it is actually a pointer to an array, since the start
    // and end indexes were both comptime-known.
    try expect(@TypeOf(slice) == *[5]u8);

    // You can also slice a slice:
    const slice2 = slice[2..3];
    try expect(slice2.len == 1);
    try expect(slice2[0] == 3);
}

$ zig test slices.zig
1/2 test "using slices for strings"... OK
2/2 test "slice pointer"... OK
All 2 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "null terminated slice" {
    const slice: [:0]const u8 = "hello";

    try expect(slice.len == 5);
    try expect(slice[5] == 0);
}

$ zig test null_terminated_slice.zig
1/1 test "null terminated slice"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "null terminated slicing" {
    var array = [_]u8{ 3, 2, 1, 0, 3, 2, 1, 0 };
    var runtime_length: usize = 3;
    const slice = array[0..runtime_length :0];

    try expect(@TypeOf(slice) == [:0]u8);
    try expect(slice.len == 3);
}

$ zig test null_terminated_slicing.zig
1/1 test "null terminated slicing"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "sentinel mismatch" {
    var array = [_]u8{ 3, 2, 1, 0 };

    // Creating a sentinel-terminated slice from the array with a length of 2
    // will result in the value `1` occupying the sentinel element position.
    // This does not match the indicated sentinel value of `0` and will lead
    // to a runtime panic.
    var runtime_length: usize = 2;
    const slice = array[0..runtime_length :0];

    _ = slice;
}

$ zig test test.zig
1/1 test "sentinel mismatch"... thread 1426374 panic: sentinel mismatch
/home/andy/tmp/zig/docgen_tmp/test.zig:12:24: 0x2078ca in test "sentinel mismatch" (test)
    const slice = array[0..runtime_length :0];
                       ^
/home/andy/tmp/zig/lib/std/special/test_runner.zig:80:28: 0x22f153 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/tmp/zig/lib/std/start.zig:551:22: 0x2284cc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/tmp/zig/lib/std/start.zig:495:12: 0x20910e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/tmp/zig/lib/std/start.zig:409:17: 0x2081a6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/tmp/zig/lib/std/start.zig:322:5: 0x207fb2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

// Declare a struct.
// Zig gives no guarantees about the order of fields and the size of
// the struct but the fields are guaranteed to be ABI-aligned.
const Point = struct {
    x: f32,
    y: f32,
};

// Maybe we want to pass it to OpenGL so we want to be particular about
// how the bytes are arranged.
const Point2 = packed struct {
    x: f32,
    y: f32,
};


// Declare an instance of a struct.
const p = Point {
    .x = 0.12,
    .y = 0.34,
};

// Maybe we're not ready to fill out some of the fields.
var p2 = Point {
    .x = 0.12,
    .y = undefined,
};

// Structs can have methods
// Struct methods are not special, they are only namespaced
// functions that you can call with dot syntax.
const Vec3 = struct {
    x: f32,
    y: f32,
    z: f32,

    pub fn init(x: f32, y: f32, z: f32) Vec3 {
        return Vec3 {
            .x = x,
            .y = y,
            .z = z,
        };
    }

    pub fn dot(self: Vec3, other: Vec3) f32 {
        return self.x * other.x + self.y * other.y + self.z * other.z;
    }
};

const expect = @import("std").testing.expect;
test "dot product" {
    const v1 = Vec3.init(1.0, 0.0, 0.0);
    const v2 = Vec3.init(0.0, 1.0, 0.0);
    try expect(v1.dot(v2) == 0.0);

    // Other than being available to call with dot syntax, struct methods are
    // not special. You can reference them as any other declaration inside
    // the struct:
    try expect(Vec3.dot(v1, v2) == 0.0);
}

// Structs can have declarations.
// Structs can have 0 fields.
const Empty = struct {
    pub const PI = 3.14;
};
test "struct namespaced variable" {
    try expect(Empty.PI == 3.14);
    try expect(@sizeOf(Empty) == 0);

    // you can still instantiate an empty struct
    const does_nothing = Empty {};

    _ = does_nothing;
}

// struct field order is determined by the compiler for optimal performance.
// however, you can still calculate a struct base pointer given a field pointer:
fn setYBasedOnX(x: *f32, y: f32) void {
    const point = @fieldParentPtr(Point, "x", x);
    point.y = y;
}
test "field parent pointer" {
    var point = Point {
        .x = 0.1234,
        .y = 0.5678,
    };
    setYBasedOnX(&point.x, 0.9);
    try expect(point.y == 0.9);
}

// You can return a struct from a function. This is how we do generics
// in Zig:
fn LinkedList(comptime T: type) type {
    return struct {
        pub const Node = struct {
            prev: ?*Node,
            next: ?*Node,
            data: T,
        };

        first: ?*Node,
        last:  ?*Node,
        len:   usize,
    };
}

test "linked list" {
    // Functions called at compile-time are memoized. This means you can
    // do this:
    try expect(LinkedList(i32) == LinkedList(i32));

    var list = LinkedList(i32) {
        .first = null,
        .last = null,
        .len = 0,
    };
    try expect(list.len == 0);

    // Since types are first class values you can instantiate the type
    // by assigning it to a variable:
    const ListOfInts = LinkedList(i32);
    try expect(ListOfInts == LinkedList(i32));

    var node = ListOfInts.Node {
        .prev = null,
        .next = null,
        .data = 1234,
    };
    var list2 = LinkedList(i32) {
        .first = &node,
        .last = &node,
        .len = 1,
    };

    // When using a pointer to a struct, fields can be accessed directly,
    // without explicitly dereferencing the pointer.
    // So you can do
    try expect(list2.first.?.data == 1234);
    // instead of try expect(list2.first.?.*.data == 1234);
}

$ zig test structs.zig
1/4 test "dot product"... OK
2/4 test "struct namespaced variable"... OK
3/4 test "field parent pointer"... OK
4/4 test "linked list"... OK
All 4 tests passed.

const Foo = struct {
    a: i32 = 1234,
    b: i32,
};

test "default struct initialization fields" {
    const x = Foo{
        .b = 5,
    };
    if (x.a + x.b != 1239) {
        @compileError("it's even comptime known!");
    }
}

$ zig test default_field_values.zig
1/1 test "default struct initialization fields"... OK
All 1 tests passed.

const std = @import("std");
const native_endian = @import("builtin").target.cpu.arch.endian();
const expect = std.testing.expect;

const Full = packed struct {
    number: u16,
};
const Divided = packed struct {
    half1: u8,
    quarter3: u4,
    quarter4: u4,
};

test "@bitCast between packed structs" {
    try doTheTest();
    comptime try doTheTest();
}

fn doTheTest() !void {
    try expect(@sizeOf(Full) == 2);
    try expect(@sizeOf(Divided) == 2);
    var full = Full{ .number = 0x1234 };
    var divided = @bitCast(Divided, full);
    switch (native_endian) {
        .Big => {
            try expect(divided.half1 == 0x12);
            try expect(divided.quarter3 == 0x3);
            try expect(divided.quarter4 == 0x4);
        },
        .Little => {
            try expect(divided.half1 == 0x34);
            try expect(divided.quarter3 == 0x2);
            try expect(divided.quarter4 == 0x1);
        },
    }
}

$ zig test packed_structs.zig
1/1 test "@bitCast between packed structs"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const BitField = packed struct {
    a: u3,
    b: u3,
    c: u2,
};

var foo = BitField{
    .a = 1,
    .b = 2,
    .c = 3,
};

test "pointer to non-byte-aligned field" {
    const ptr = &foo.b;
    try expect(ptr.* == 2);
}

$ zig test pointer_to_non-byte_aligned_field.zig
1/1 test "pointer to non-byte-aligned field"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const BitField = packed struct {
    a: u3,
    b: u3,
    c: u2,
};

var bit_field = BitField{
    .a = 1,
    .b = 2,
    .c = 3,
};

test "pointer to non-bit-aligned field" {
    try expect(bar(&bit_field.b) == 2);
}

fn bar(x: *const u3) u3 {
    return x.*;
}

$ zig test test.zig
./docgen_tmp/test.zig:17:30: error: expected type '*const u3', found '*align(:3:1) u3'
    try expect(bar(&bit_field.b) == 2);
                             ^

const std = @import("std");
const expect = std.testing.expect;

const BitField = packed struct {
    a: u3,
    b: u3,
    c: u2,
};

var bit_field = BitField{
    .a = 1,
    .b = 2,
    .c = 3,
};

test "pointer to non-bit-aligned field" {
    try expect(@ptrToInt(&bit_field.a) == @ptrToInt(&bit_field.b));
    try expect(@ptrToInt(&bit_field.a) == @ptrToInt(&bit_field.c));
}

$ zig test pointer_to_non-bit_aligned_field.zig
1/1 test "pointer to non-bit-aligned field"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const BitField = packed struct {
    a: u3,
    b: u3,
    c: u2,
};

test "pointer to non-bit-aligned field" {
    comptime {
        try expect(@bitOffsetOf(BitField, "a") == 0);
        try expect(@bitOffsetOf(BitField, "b") == 3);
        try expect(@bitOffsetOf(BitField, "c") == 6);

        try expect(@offsetOf(BitField, "a") == 0);
        try expect(@offsetOf(BitField, "b") == 0);
        try expect(@offsetOf(BitField, "c") == 0);
    }
}

$ zig test test_bitOffsetOf_offsetOf.zig
1/1 test "pointer to non-bit-aligned field"... OK
All 1 tests passed.

const S = packed struct {
    a: u32,
    b: u32,
};
test "overaligned pointer to packed struct" {
    var foo: S align(4) = undefined;
    const ptr: *align(4) S = &foo;
    const ptr_to_b: *u32 = &ptr.b;
    _ = ptr_to_b;
}

$ zig test test.zig
./docgen_tmp/test.zig:8:32: error: expected type '*u32', found '*align(1) u32'
    const ptr_to_b: *u32 = &ptr.b;
                               ^

const std = @import("std");
const expectEqual = std.testing.expectEqual;

test "aligned struct fields" {
    const S = struct {
        a: u32 align(2),
        b: u32 align(64),
    };
    var foo = S{ .a = 1, .b = 2 };

    try expectEqual(64, @alignOf(S));
    try expectEqual(*align(2) u32, @TypeOf(&foo.a));
    try expectEqual(*align(64) u32, @TypeOf(&foo.b));
}

$ zig test test_aligned_struct_fields.zig
1/1 test "aligned struct fields"... OK
All 1 tests passed.

const std = @import("std");

pub fn main() void {
    const Foo = struct {};
    std.debug.print("variable: {s}\n", .{@typeName(Foo)});
    std.debug.print("anonymous: {s}\n", .{@typeName(struct {})});
    std.debug.print("function: {s}\n", .{@typeName(List(i32))});
}

fn List(comptime T: type) type {
    return struct {
        x: T,
    };
}

$ zig build-exe struct_name.zig

$ ./struct_name
variable: Foo
anonymous: struct:6:53
function: List(i32)

const std = @import("std");
const expect = std.testing.expect;

const Point = struct {x: i32, y: i32};

test "anonymous struct literal" {
    var pt: Point = .{
        .x = 13,
        .y = 67,
    };
    try expect(pt.x == 13);
    try expect(pt.y == 67);
}

$ zig test struct_result.zig
1/1 test "anonymous struct literal"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "fully anonymous struct" {
    try dump(.{
        .int = @as(u32, 1234),
        .float = @as(f64, 12.34),
        .b = true,
        .s = "hi",
    });
}

fn dump(args: anytype) !void {
    try expect(args.int == 1234);
    try expect(args.float == 12.34);
    try expect(args.b);
    try expect(args.s[0] == 'h');
    try expect(args.s[1] == 'i');
}

$ zig test struct_anon.zig
1/1 test "fully anonymous struct"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

test "tuple" {
    const values = .{
        @as(u32, 1234),
        @as(f64, 12.34),
        true,
        "hi",
    } ++ .{false} ** 2;
    try expect(values[0] == 1234);
    try expect(values[4] == false);
    inline for (values) |v, i| {
        if (i != 2) continue;
        try expect(v);
    }
    try expect(values.len == 6);
    try expect(values.@"3"[0] == 'h');
}

$ zig test tuple.zig
1/1 test "tuple"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;
const mem = @import("std").mem;

// Declare an enum.
const Type = enum {
    ok,
    not_ok,
};

// Declare a specific instance of the enum variant.
const c = Type.ok;

// If you want access to the ordinal value of an enum, you
// can specify the tag type.
const Value = enum(u2) {
    zero,
    one,
    two,
};

// Now you can cast between u2 and Value.
// The ordinal value starts from 0, counting up for each member.
test "enum ordinal value" {
    try expect(@enumToInt(Value.zero) == 0);
    try expect(@enumToInt(Value.one) == 1);
    try expect(@enumToInt(Value.two) == 2);
}

// You can override the ordinal value for an enum.
const Value2 = enum(u32) {
    hundred = 100,
    thousand = 1000,
    million = 1000000,
};
test "set enum ordinal value" {
    try expect(@enumToInt(Value2.hundred) == 100);
    try expect(@enumToInt(Value2.thousand) == 1000);
    try expect(@enumToInt(Value2.million) == 1000000);
}

// Enums can have methods, the same as structs and unions.
// Enum methods are not special, they are only namespaced
// functions that you can call with dot syntax.
const Suit = enum {
    clubs,
    spades,
    diamonds,
    hearts,

    pub fn isClubs(self: Suit) bool {
        return self == Suit.clubs;
    }
};
test "enum method" {
    const p = Suit.spades;
    try expect(!p.isClubs());
}

// An enum variant of different types can be switched upon.
const Foo = enum {
    string,
    number,
    none,
};
test "enum variant switch" {
    const p = Foo.number;
    const what_is_it = switch (p) {
        Foo.string => "this is a string",
        Foo.number => "this is a number",
        Foo.none => "this is a none",
    };
    try expect(mem.eql(u8, what_is_it, "this is a number"));
}

// @typeInfo can be used to access the integer tag type of an enum.
const Small = enum {
    one,
    two,
    three,
    four,
};
test "std.meta.Tag" {
    try expect(@typeInfo(Small).Enum.tag_type == u2);
}

// @typeInfo tells us the field count and the fields names:
test "@typeInfo" {
    try expect(@typeInfo(Small).Enum.fields.len == 4);
    try expect(mem.eql(u8, @typeInfo(Small).Enum.fields[1].name, "two"));
}

// @tagName gives a [:0]const u8 representation of an enum value:
test "@tagName" {
    try expect(mem.eql(u8, @tagName(Small.three), "three"));
}

$ zig test enums.zig
1/7 test "enum ordinal value"... OK
2/7 test "set enum ordinal value"... OK
3/7 test "enum method"... OK
4/7 test "enum variant switch"... OK
5/7 test "std.meta.Tag"... OK
6/7 test "@typeInfo"... OK
7/7 test "@tagName"... OK
All 7 tests passed.

const Foo = enum { a, b, c };
export fn entry(foo: Foo) void { _ = foo; }

$ zig build-obj test.zig
./docgen_tmp/test.zig:2:22: error: parameter of type 'Foo' not allowed in function with calling convention 'C'
export fn entry(foo: Foo) void { _ = foo; }
                     ^

const Foo = enum(c_int) { a, b, c };
export fn entry(foo: Foo) void { _ = foo; }

$ zig build-obj test.zig

const std = @import("std");
const expect = std.testing.expect;

const Color = enum {
    auto,
    off,
    on,
};

test "enum literals" {
    const color1: Color = .auto;
    const color2 = Color.auto;
    try expect(color1 == color2);
}

test "switch using enum literals" {
    const color = Color.on;
    const result = switch (color) {
        .auto => false,
        .on => true,
        .off => false,
    };
    try expect(result);
}

$ zig test test_enum_literals.zig
1/2 test "enum literals"... OK
2/2 test "switch using enum literals"... OK
All 2 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const Number = enum(u8) {
    one,
    two,
    three,
    _,
};

test "switch on non-exhaustive enum" {
    const number = Number.one;
    const result = switch (number) {
        .one => true,
        .two,
        .three => false,
        _ => false,
    };
    try expect(result);
    const is_one = switch (number) {
        .one => true,
        else => false,
    };
    try expect(is_one);
}

$ zig test test_switch_non-exhaustive.zig
1/1 test "switch on non-exhaustive enum"... OK
All 1 tests passed.

const Payload = union {
    int: i64,
    float: f64,
    boolean: bool,
};
test "simple union" {
    var payload = Payload{ .int = 1234 };
    payload.float = 12.34;
}

$ zig test test.zig
1/1 test "simple union"... thread 1427497 panic: access of inactive union field
/home/andy/tmp/zig/docgen_tmp/test.zig:8:12: 0x2078db in test "simple union" (test)
    payload.float = 12.34;
           ^
/home/andy/tmp/zig/lib/std/special/test_runner.zig:80:28: 0x22f143 in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/tmp/zig/lib/std/start.zig:551:22: 0x2284bc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/tmp/zig/lib/std/start.zig:495:12: 0x2090fe in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/tmp/zig/lib/std/start.zig:409:17: 0x208196 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/tmp/zig/lib/std/start.zig:322:5: 0x207fa2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/e62d5b643d08f1acbb1386db92eb0f23/test /home/andy/tmp/zig/build-release/zig

const std = @import("std");
const expect = std.testing.expect;

const Payload = union {
    int: i64,
    float: f64,
    boolean: bool,
};
test "simple union" {
    var payload = Payload{ .int = 1234 };
    try expect(payload.int == 1234);
    payload = Payload{ .float = 12.34 };
    try expect(payload.float == 12.34);
}

$ zig test test_simple_union.zig
1/1 test "simple union"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const ComplexTypeTag = enum {
    ok,
    not_ok,
};
const ComplexType = union(ComplexTypeTag) {
    ok: u8,
    not_ok: void,
};

test "switch on tagged union" {
    const c = ComplexType{ .ok = 42 };
    try expect(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);

    switch (c) {
        ComplexTypeTag.ok => |value| try expect(value == 42),
        ComplexTypeTag.not_ok => unreachable,
    }
}

test "get tag type" {
    try expect(std.meta.Tag(ComplexType) == ComplexTypeTag);
}

test "coerce to enum" {
    const c1 = ComplexType{ .ok = 42 };
    const c2 = ComplexType.not_ok;

    try expect(c1 == .ok);
    try expect(c2 == .not_ok);
}

$ zig test test_switch_tagged_union.zig
1/3 test "switch on tagged union"... OK
2/3 test "get tag type"... OK
3/3 test "coerce to enum"... OK
All 3 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const ComplexTypeTag = enum {
    ok,
    not_ok,
};
const ComplexType = union(ComplexTypeTag) {
    ok: u8,
    not_ok: void,
};

test "modify tagged union in switch" {
    var c = ComplexType{ .ok = 42 };
    try expect(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);

    switch (c) {
        ComplexTypeTag.ok => |*value| value.* += 1,
        ComplexTypeTag.not_ok => unreachable,
    }

    try expect(c.ok == 43);
}

$ zig test test_switch_modify_tagged_union.zig
1/1 test "modify tagged union in switch"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const Variant = union(enum) {
    int: i32,
    boolean: bool,

    // void can be omitted when inferring enum tag type.
    none,

    fn truthy(self: Variant) bool {
        return switch (self) {
            Variant.int => |x_int| x_int != 0,
            Variant.boolean => |x_bool| x_bool,
            Variant.none => false,
        };
    }
};

test "union method" {
    var v1 = Variant{ .int = 1 };
    var v2 = Variant{ .boolean = false };

    try expect(v1.truthy());
    try expect(!v2.truthy());
}

$ zig test test_union_method.zig
1/1 test "union method"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const Small2 = union(enum) {
    a: i32,
    b: bool,
    c: u8,
};
test "@tagName" {
    try expect(std.mem.eql(u8, @tagName(Small2.a), "a"));
}

$ zig test test_tagName.zig
1/1 test "@tagName"... OK
All 1 tests passed.

const std = @import("std");
const expect = std.testing.expect;

const Number = union {
    int: i32,
    float: f64,
};

test "anonymous union literal syntax" {
    var i: Number = .{.int = 42};
    var f = makeNumber();
    try expect(i.int == 42);
    try expect(f.float == 12.34);
}

fn makeNumber() Number {
    return .{.float = 12.34};
}

$ zig test anon_union.zig
1/1 test "anonymous union literal syntax"... OK
All 1 tests passed.

const Derp = opaque {};
const Wat = opaque {};

extern fn bar(d: *Derp) void;
fn foo(w: *Wat) callconv(.C) void {
    bar(w);
}

test "call foo" {
    foo(undefined);
}

$ zig test test.zig
./docgen_tmp/test.zig:6:9: error: expected type '*Derp', found '*Wat'
    bar(w);
        ^
./docgen_tmp/test.zig:6:9: note: pointer type child 'Wat' cannot cast into pointer type child 'Derp'
    bar(w);
        ^

test "access variable after block scope" {
    {
        var x: i32 = 1;
        _ = x;
    }
    x += 1;
}

$ zig test test.zig
docgen_tmp/test.zig:6:5: error: use of undeclared identifier 'x'
    x += 1;
    ^

const std = @import("std");
const expect = std.testing.expect;

test "labeled break from labeled block expression" {
    var y: i32 = 123;

    const x = blk: {
        y += 1;
        break :blk y;
    };
    try expect(x == 124);
    try expect(y == 124);
}

$ zig test test_labeled_break.zig
1/1 test "labeled break from labeled block expression"... OK
All 1 tests passed.

const pi = 3.14;

test "inside test block" {
    // Let's even go inside another block
    {
        var pi: i32 = 1234;
    }
}

$ zig test test.zig
docgen_tmp/test.zig:6:13: error: local shadows declaration of 'pi'
        var pi: i32 = 1234;
            ^
docgen_tmp/test.zig:1:1: note: declared here
const pi = 3.14;
^

test "separate scopes" {
    {
        const pi = 3.14;
        _ = pi;
    }
    {
        var pi: bool = true;
        _ = pi;
    }
}

$ zig test test_scopes.zig
1/1 test "separate scopes"... OK
All 1 tests passed.

const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;

test "switch simple" {
    const a: u64 = 10;
    const zz: u64 = 103;

    // All branches of a switch expression must be able to be coerced to a
    // common type.
    //
    // Branches cannot fallthrough. If fallthrough behavior is desired, combine
    // the cases and use an if.
    const b = switch (a) {
        // Multiple cases can be combined via a ','
        1, 2, 3 => 0,

        // Ranges can be specified using the ... syntax. These are inclusive
        // of both ends.
        5...100 => 1,

        // Branches can be arbitrarily complex.
        101 => blk: {
            const c: u64 = 5;
            break :blk c * 2 + 1;
        },

        // Switching on arbitrary expressions is allowed as long as the
        // expression is known at compile-time.
        zz => zz,
        blk: {
            const d: u32 = 5;
            const e: u32 = 100;
            break :blk d + e;
        } => 107,

        // The else branch catches everything not already captured.
        // Else branches are mandatory unless the entire range of values
        // is handled.
        else => 9,
    };

    try expect(b == 1);
}

// Switch expressions can be used outside a function:
const os_msg = switch (builtin.target.os.tag) {
    .linux => "we found a linux user",
    else => "not a linux user",
};

// Inside a function, switch statements implicitly are compile-time
// evaluated if the target expression is compile-time known.
test "switch inside function" {
    switch (builtin.target.os.tag) {
        .fuchsia => {
            // On an OS other than fuchsia, block is not even analyzed,
            // so this compile error is not triggered.
            // On fuchsia this compile error would be triggered.
            @compileError("fuchsia not supported");
        },
        else => {},
    }
}

$ zig test switch.zig
1/2 test "switch simple"... OK
2/2 test "switch inside function"... OK
All 2 tests passed.

const expect = @import("std").testing.expect;

test "switch on tagged union" {
    const Point = struct {
        x: u8,
        y: u8,
    };
    const Item = union(enum) {
        a: u32,
        c: Point,
        d,
        e: u32,
    };

    var a = Item{ .c = Point{ .x = 1, .y = 2 } };

    // Switching on more complex enums is allowed.
    const b = switch (a) {
        // A capture group is allowed on a match, and will return the enum
        // value matched. If the payload types of both cases are the same
        // they can be put into the same switch prong.
        Item.a, Item.e => |item| item,

        // A reference to the matched value can be obtained using `*` syntax.
        Item.c => |*item| blk: {
            item.*.x += 1;
            break :blk 6;
        },

        // No else is required if the types cases was exhaustively handled
        Item.d => 8,
    };

    try expect(b == 6);
    try expect(a.c.x == 2);
}

$ zig test test_switch_tagged_union.zig
1/1 test "switch on tagged union"... OK
All 1 tests passed.

const Color = enum {
    auto,
    off,
    on,
};

test "exhaustive switching" {
    const color = Color.off;
    switch (color) {
        Color.auto => {},
        Color.on => {},
    }
}

$ zig test test.zig
./docgen_tmp/test.zig:9:5: error: enumeration value 'Color.off' not handled in switch
    switch (color) {
    ^

const std = @import("std");
const expect = std.testing.expect;

const Color = enum {
    auto,
    off,
    on,
};

test "enum literals with switch" {
    const color = Color.off;
    const result = switch (color) {
        .auto => false,
        .on => false,
        .off => true,
    };
    try expect(result);
}

$ zig test test_exhaustive_switch.zig
1/1 test "enum literals with switch"... OK
All 1 tests passed.

const expect = @import("std").testing.expect;

test "while basic" {
    var i: usize = 0;
    while (i < 10) {
        i += 1;
    }
    try expect(i == 10);
}