Zig

https://ziglang.org/documentation/
Admin
Zig is a general-purpose programming language designed for robustness, optimality, and...
Tokens:1,289,217
Snippets:7,188
Trust Score:9.6
Update:2 days ago
Show doc for...
Tokens:
Raw
### printf.zig setup

Source: https://ziglang.org/documentation/0.6.0

Initial setup for a printf implementation in Zig.

```zig
const warn = @import("std").debug.warn;

const a_number: i32 = 1234;
const a_string = "foobar";
```

--------------------------------

### Runtime Unreachable Code Setup

Source: https://ziglang.org/documentation/0.3.0

Initial setup for a runtime unreachable code example.

```zig
const std = @import("std");
```

--------------------------------

### Build and run print example

Source: https://ziglang.org/documentation/0.14.1

Commands to compile and execute the print_comptime-known_format.zig example.

```shell
$ zig build-exe print_comptime-known_format.zig
$ ./print_comptime-known_format
here is a string: 'foobar' here is a number: 1234
```

--------------------------------

### Zig Style Guide Example

Source: https://ziglang.org/documentation/0.10.1

A comprehensive example demonstrating the recommended naming conventions for namespaces, types, variables, functions, and structs in Zig.

```zig
const namespace_name = @import("dir_name/file_name.zig");
const TypeName = @import("dir_name/TypeName.zig");
var global_var: i32 = undefined;
const const_name = 42;
const primitive_type_alias = f32;
const string_alias = []u8;

const StructName = struct {
    field: i32,
};
const StructAlias = StructName;

fn functionName(param_name: TypeName) void {
    var functionPointer = functionName;
    functionPointer();
    functionPointer = otherFunction;
    functionPointer();
}
const functionAlias = functionName;

fn ListTemplateFunction(comptime ChildType: type, comptime fixed_size: usize) type {
    return List(ChildType, fixed_size);
}

fn ShortList(comptime T: type, comptime n: usize) type {
    return struct {
        field_name: [n]T,
        fn methodName() void {}
    };
}

// The word XML loses its casing when used in Zig identifiers.
const xml_document =
    \\<?xml version="1.0" encoding="UTF-8"?>
    \\<document>
    \\</document>
;
const XmlParser = struct {
    field: i32,
};

// The initials BE (Big Endian) are just another word in Zig identifier names.
fn readU32Be() u32 {}
```

--------------------------------

### Build and Run Assembly Example

Source: https://ziglang.org/documentation/0.9.1

Commands to compile and execute the assembly example.

```shell
$ `zig build-exe test.zig -target x86_64-linux`

$ `./test`
hello world
```

--------------------------------

### Pointer test setup

Source: https://ziglang.org/documentation/0.3.0

Initial setup for pointer testing.

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

--------------------------------

### Building and running the CLI allocation example

Source: https://ziglang.org/documentation/0.17.0

Commands to compile and execute the ArenaAllocator example.

```shell
$ `zig build-exe cli_allocation.zig`
$ `./cli_allocation`
ptr=i32@730773e58018
```

--------------------------------

### Compile-time test setup

Source: https://ziglang.org/documentation/0.8.1

Initial setup for testing compile-time and run-time function calls.

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

--------------------------------

### Build and run the main entry point example

Source: https://ziglang.org/documentation/0.15.2

Commands to compile and execute the entry_point.zig file.

```shell
$ `zig build-exe entry_point.zig`
$ `./entry_point`
Hello, World!
```

--------------------------------

### Build and run the assembly example

Source: https://ziglang.org/documentation/0.4.0

Commands to compile the test.zig file and execute the resulting binary.

```bash
$ zig build-exe test.zig
$ ./test
hello world
```

--------------------------------

### Inline Switch Prongs Unrolled Function

Source: https://ziglang.org/documentation/0.17.0

An example showing how calls to a function with an inline switch get unrolled.

```zig
fn isFieldOptionalUnrolled(field_index: usize) !bool {
    return switch (field_index) {
        0 => false,
        1 => true,
        else => return error.IndexOutOfBounds,
    };
}
```

--------------------------------

### Integrate Zig library with C using Build System

Source: https://ziglang.org/documentation/0.10.1

Example showing a C main file, a build.zig configuration, and the command to run the test.

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

int main(int argc, char **argv) {
    int32_t result = add(42, 1337);
    printf("%d\n", result);
    return 0;
}
```

```zig
const Builder = @import("std").build.Builder;

pub fn build(b: *Builder) void {
    const lib = b.addSharedLibrary("mathtest", "mathtest.zig", b.version(1, 0, 0));

    const exe = b.addExecutable("test", null);
    exe.addCSourceFile("test.c", &[_][]const u8{"-std=c99"});
    exe.linkLibrary(lib);
    exe.linkSystemLibrary("c");

    b.default_step.dependOn(&exe.step);

    const run_cmd = exe.run();

    const test_step = b.step("test", "Test the program");
    test_step.dependOn(&run_cmd.step);
}
```

```shell
$ `zig build test`
1379
```

--------------------------------

### Enum variant switch and @typeInfo/@tagName examples

Source: https://ziglang.org/documentation/0.8.1

Examples showing how to switch on enum variants, use @typeInfo to access the integer tag type and field information, and use @tagName to get a string representation of an enum value.

```zig
// 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 []const u8 representation of an enum value:
test "@tagName" {
    try expect(mem.eql(u8, @tagName(Small.three), "three"));
}
```

```shell
$ zig test enums.zig
Test [1/7] test "enum ordinal value"... 
Test [2/7] test "set enum ordinal value"... 
Test [3/7] test "enum method"... 
Test [4/7] test "enum variant switch"... 
Test [5/7] test "std.meta.Tag"... 
Test [6/7] test "@typeInfo"... 
Test [7/7] test "@tagName"... 

All 7 tests passed.

```

--------------------------------

### Style Guide: Avoid Redundant Names in Fully-Qualified Namespaces

Source: https://ziglang.org/documentation/0.13.0

Zig example showing a redundant name 'JsonValue' inside a 'json' namespace. The output is 'redundant_fqn.json.JsonValue' when compiled and run.

```Zig
const std = @import("std");

pub const json = struct {
    pub const JsonValue = union(enum) {
        number: f64,
        boolean: bool,
        // ...
    };
};

pub fn main() void {
    std.debug.print("{s}\n", .{@typeName(json.JsonValue)});
}
```

```Shell
$ `zig build-exe redundant_fqn.zig`
$ `./redundant_fqn`
redundant_fqn.json.JsonValue
```

--------------------------------

### Enum Declaration Example

Source: https://ziglang.org/documentation/0.4.0

Example of an enum declaration structure.

```zig
pub const Inline = enum {
    Auto,
    Always,
    Never,
};
            };
        };
    };
};
```

--------------------------------

### WebAssembly WASI Example

Source: https://ziglang.org/documentation/0.6.0

Demonstrates using the standard library and command line arguments with WASI.

```zig
const std = @import("std");

pub fn main() !void {
    // TODO a better default allocator that isn't as wasteful!
    const args = try std.process.argsAlloc(std.heap.page_allocator);
    defer std.process.argsFree(std.heap.page_allocator, args);

    for (args) |arg, i| {
        std.debug.warn("{}: {}\n", .{i, arg});
    }
}
```

```bash
$ zig build-exe wasi.zig -target wasm32-wasi
```

```bash
$ wasmer run wasi.wasm 123 hello
0: wasi.wasm
1: 123
2: hello
```

--------------------------------

### Building and Running the Print Example

Source: https://ziglang.org/documentation/0.10.1

Commands to compile and execute the print example, showing the resulting output.

```shell
$ `zig build-exe print.zig`

$ `./print`
here is a string: 'foobar' here is a number: 1234
```

--------------------------------

### Wrapping Negation Example

Source: https://ziglang.org/documentation/0.16.0

Example usage of the wrapping negation operator.

```zig
-%@as(i8, -128) == -128
```

--------------------------------

### Build and run the libc export entry point example

Source: https://ziglang.org/documentation/0.15.2

Commands to compile with libc linking and execute the libc_export_entry_point.zig file.

```shell
$ `zig build-exe libc_export_entry_point.zig -lc`
$ `./libc_export_entry_point`
Hello! argv[0] is './libc_export_entry_point'
```

--------------------------------

### Using Zig with the C Build System

Source: https://ziglang.org/documentation/0.13.0

Example showing a C main file and a Zig build script to compile and link a library.

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

int main(int argc, char **argv) {
    int32_t result = add(42, 1337);
    printf("%d\n", result);
    return 0;
}
```

```zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    const lib = b.addSharedLibrary(.{
        .name = "mathtest",
        .root_source_file = b.path("mathtest.zig"),
        .version = .{ .major = 1, .minor = 0, .patch = 0 },
    });
    const exe = b.addExecutable(.{
        .name = "test",
    });
    exe.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
    exe.linkLibrary(lib);
    exe.linkSystemLibrary("c");

    b.default_step.dependOn(&exe.step);

    const run_cmd = exe.run();

    const test_step = b.step("test", "Test the program");
    test_step.dependOn(&run_cmd.step);
}
```

--------------------------------

### Wrapping Subtraction Example

Source: https://ziglang.org/documentation/0.16.0

Example usage of the wrapping subtraction operator.

```zig
@as(u8, 0) -% 1 == 255
```

--------------------------------

### Saturating Addition Example

Source: https://ziglang.org/documentation/0.16.0

Example usage of the saturating addition operator.

```zig
@as(u8, 255) +| 1 == @as(u8, 255)
```

--------------------------------

### C library integration example

Source: https://ziglang.org/documentation/0.5.0

A complete example showing a C main file and a build.zig script to link against a Zig-exported library.

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

int main(int argc, char **argv) {
    int32_t result = add(42, 1337);
    printf("%d\n", result);
    return 0;
}
```

```zig
const Builder = @import("std").build.Builder;

pub fn build(b: *Builder) void {
    const lib = b.addSharedLibrary("mathtest", "mathtest.zig", b.version(1, 0, 0));

    const exe = b.addExecutable("test", null);
    exe.addCSourceFile("test.c", [_][]const u8{"-std=c99"});
    exe.linkLibrary(lib);
    exe.linkSystemLibrary("c");

    b.default_step.dependOn(&exe.step);

    const run_cmd = exe.run();

    const test_step = b.step("test", "Test the program");
    test_step.dependOn(&run_cmd.step);
}
```

--------------------------------

### Wrapping Addition Example

Source: https://ziglang.org/documentation/0.16.0

Example usage of the wrapping addition operator.

```zig
@as(u32, 0xffffffff) +% 1 == 0
```

--------------------------------

### Bit Shift Left Example

Source: https://ziglang.org/documentation/0.14.1

Example of bit shift left.

```zig
0b1 << 8 == 0b100000000
```

--------------------------------

### Wrapping operations setup

Source: https://ziglang.org/documentation/0.8.1

Initial imports for demonstrating wrapping arithmetic operations.

```zig
const std = @import("std");
const expect = std.testing.expect;
const minInt = std.math.minInt;
const maxInt = std.math.maxInt;
```

--------------------------------

### C library integration example

Source: https://ziglang.org/documentation/0.7.1

A complete example showing a C main file and a Zig build system configuration to link a Zig-exported library.

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

int main(int argc, char **argv) {
    int32_t result = add(42, 1337);
    printf("%d\n", result);
    return 0;
}
```

```zig
const Builder = @import("std").build.Builder;

pub fn build(b: *Builder) void {
    const lib = b.addSharedLibrary("mathtest", "mathtest.zig", b.version(1, 0, 0));

    const exe = b.addExecutable("test", null);
    exe.addCSourceFile("test.c", &[_][]const u8{"-std=c99"});
    exe.linkLibrary(lib);
    exe.linkSystemLibrary("c");

    b.default_step.dependOn(&exe.step);

    const run_cmd = exe.run();

    const test_step = b.step("test", "Test the program");
    test_step.dependOn(&run_cmd.step);
}
```

--------------------------------

### Zig test output

Source: https://ziglang.org/documentation/0.3.0

Example output from running tests on the struct examples.

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

--------------------------------

### Unbounded Lookahead Example: BoolOrExpr

Source: https://ziglang.org/documentation/0.17.0

An example of a repetition rule that requires unbounded lookahead.

```peg
BoolOrExpr <- BoolAndExpr (OrOp BoolAndExpr)*
```
Tokens:
Raw