Zig in 30 minutes

test.md

A half-hour to learn Zig

This is inspired by https://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/

Basics

the command zig run my_code.zig will compile and immediately run your Zig program. Each of these cells contains a zig program that you can try to run (some of them contain compile-time errors that you can comment out to play with)

You'll want to declare a main() function to get started running code.

This program does almost nothing:

// comments look like this and go to the end of the line
pub fn main() void {}

You can import from the standard library by using the @import builtin and assigning the namespace to a const value. Almost everything in zig must be explicitly assigned its identifier. You can also import other zig files this way, and C files in a similar fashion with @cImport.

const std = @import("std");

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

Note:

• I'll explain the funny second parameter in the print statement, later in the structs section.

var declares a variable, in most cases you should declare the variable type.

const std = @import("std");

pub fn main() void {
    var x: i32 = 47; // declares "x" of type i32 to be 47.
    std.debug.print("x: {}\n", .{x});
}

const declares that a variable's value is immutable.

pub fn main() void {
    const x: i32 = 47;
    x = 42; // error: cannot assign to constant
}

Zig is very picky and will NOT let you shadow identifiers from an outside scope, to keep you from being confused:

const x: i32 = 47;

pub fn main() void {
    var x: i32 = 42;  // error: redefinition of 'x'
}

Constants in the global scope are by default compile-time "comptime" values, and if you omit the type they are comptime typed and can turn into runtime types for your runtime values.

const x: i32 = 47;
const y = -47;  // comptime integer.

pub fn main() void {
    var a: i32 = y; // comptime constant coerced into correct type
    var b: i64 = y; // comptime constant coerced into correct type
    var c: u32 = y; // error: cannot cast negative value -47 to unsigned integer
}

You can explicitly choose to leave it undefined if it will get set later. Zig will fill in a dummy value with 0XAA bytes to help detect errors in debug mode if you cause an error from accidentally using it in debug.

const std = @import("std");

pub fn main() void {
  var x: i32 = undefined;
  std.debug.print("undefined: {}\n", .{x});
}

In some cases, zig will let you omit the type information if it can figure it out.

const std = @import("std");

pub fn main() void {
    var x: i32 = 47;
    var y: i32 = 47;
    var z = x + y; // declares z and sets it to 94.
    std.debug.print("z: {}\n", .{z});
}

But be careful, integer literals are comptime-typed, so this won't work:

pub fn main() void {
    var x = 47; // error: variable of type 'comptime_int' must be const or comptime
}

Functions

Here's a function (foo) that returns nothing. The pub keyword means that the function is exportable from the current scope, which is why main must be pub. You call functions just as you would in most programming languages:

const std = @import("std");

fn foo() void {
    std.debug.print("foo!\n", .{});

    //optional:
    return;
}

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

Here's a function that returns an integer value:

const std = @import("std");

fn foo() i32 {
    return 47;
}

pub fn main() void {
    var result = foo();
    std.debug.print("foo: {}\n", .{result});
}

Zig won't let you ignore return values for functions:

fn foo() i32 {
    return 47;
}

pub fn main() void {
    foo(); // error: expression value is ignored
}

but you can if you assign it to the throw-away _.

fn foo() i32 {
    return 47;
}

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

You can make a function that can take a parameter by declaring its type:

const std = @import("std");

fn foo(x: i32) void {
    std.debug.print("foo param: {}\n", .{x});
}

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

Structs

structs are declared by assigning them a name using the const keyword, they can be assigned out of order, and they can be used by dereferencing with the usual dot syntax.

const std = @import("std");

const Vec2 = struct{
    x: f64,
    y: f64
};

pub fn main() void {
    var v = Vec2{.y = 1.0, .x = 2.0};
    std.debug.print("v: {}\n", .{v});
}

structs can have default values; structs can also be anonymous, and can coerce into another struct so long as all of the values can be figured out:

const std = @import("std");

const Vec3 = struct{
    x: f64 = 0.0,
    y: f64,
    z: f64
};

pub fn main() void {
    var v: Vec3 = .{.y = 0.1, .z = 0.2};  // ok
    var w: Vec3 = .{.y = 0.1}; // error: missing field: 'z'
    std.debug.print("v: {}\n", .{v});
}

You can drop functions into an struct to make it work like a OOP-style object. There is syntactic sugar where if you make the functions' first parameter be a pointer to the object, it can be called "Object-style", similar to how Python has the self-parametered member functions. The typical convention is to make this obvious by calling the variable self.

const std = @import("std");

const LikeAnObject = struct{
    value: i32,

    fn print(self: *LikeAnObject) void {
        std.debug.print("value: {}\n", .{self.value});
    }
};

pub fn main() void {
    var obj = LikeAnObject{.value = 47};
    obj.print();
}

By the way, that thing we've been passing into the std.debug.print's second parameter is a tuple. Without going into too much detail, it's an anonymous struct with number fields.
At compile time, std.debug.print figures out types of the parameters in that tuple and generates a version of itself tuned for the parameters string that you provided, and that's how zig knows how to make the contents of the print pretty.

const std = @import("std");

pub fn main() void {
    std.debug.print("{}\n", .{1, 2}); #  error: Unused arguments
}

Enums

Enums are declared by assigning the group of enums as a type using the const keyword.

Note:

• In some cases you can shortcut the name of the Enum.
• You can set the value of an Enum to an integer, but it does not automatically coerce, you have to use @enumToInt or @intToEnum to do conversions.

const std = @import("std");

const EnumType = enum{
    EnumOne,
    EnumTwo,
    EnumThree = 3
};

pub fn main() void {
    std.debug.print("One: {}\n", .{EnumType.EnumOne});
    std.debug.print("Two?: {}\n", .{EnumType.EnumTwo == .EnumTwo});
    std.debug.print("Three?: {}\n", .{@enumToInt(EnumType.EnumThree) == 3});
}

Arrays and Slices

zig has Arrays, which are contiguous memory with compile-time known length. You can initialize them by declaring the type up front and providing the list of values. You can access the length with the len field of the array.

Note:

• Arrays in zig are zero-indexed.

const std = @import("std");

pub fn main() void {
    var array: [3]u32 = [3]u32{47, 47, 47};

    // also valid:
    // var array = [_]u32{47, 47, 47};

    var invalid = array[4]; // error: index 4 outside array of size 3.
    std.debug.print("array[0]: {}\n", .{array[0]});
    std.debug.print("length: {}\n", .{array.len});
}

zig also has slices, which are have run-time known length. You can construct slices from arrays or other slices using the slicing operation. Similarly to arrays, slices have a len field which tells you its length.

Note:

• The interval parameter in the slicing operation is open (non-inclusive) on the big end.

Attempting to access beyond the range of the slice is a runtime panic (this means your program will crash).

const std = @import("std");

pub fn main() void {
    var array: [3]u32 = [_]u32{47, 47, 47};
    var slice: []u32 = array[0..2];

    // also valid:
    // var slice = array[0..2];

    var invalid = slice[3]; // panic: index out of bounds

    std.debug.print("slice[0]: {}\n", .{slice[0]});
    std.debug.print("length: {}\n", .{slice.len});
}

string literals are null-terminated utf-8 encoded arrays of const u8 bytes.
Unicode characters are only allowed in string literals and comments.

Note:

• length does not include the null termination (officially called "sentinel termination")
• it's safe to access the null terminator.
• indices are by byte, not by unicode glyph.

const std = @import("std");
const string = "hello 世界";
const world = "world";

pub fn main() void {
    var slice: []const u8 = string[0..5];

    std.debug.print("string {}\n", .{string});
    std.debug.print("length {}\n", .{world.len});
    std.debug.print("null {}\n", .{world[5]});
    std.debug.print("slice {}\n", .{slice});
    std.debug.print("huh? {}\n", .{string[0..7]});
}

const arrays can be coerced into const slices.

const std = @import("std");

fn foo() []const u8 {  // note function returns a slice
    return "foo";      // but this is a const array.
}

pub fn main() void {
    std.debug.print("foo: {}\n", .{foo()});
}

Control structures

Zig gives you an if statement that works as you would expect.

const std = @import("std");

fn foo(v: i32) []const u8 {
    if (v < 0) {
        return "negative";
    }
    else {
        return "non-negative";
    }
}

pub fn main() void {
    std.debug.print("positive {}\n", .{foo(47)});
    std.debug.print("negative {}\n", .{foo(-47)});
}

as well as a switch statement

const std = @import("std");

fn foo(v: i32) []const u8 {
    switch (v) {
        0 => return "zero",
        else => return "nonzero"
    }
}

pub fn main() void {
    std.debug.print("47 {}\n", .{foo(47)});
    std.debug.print("0 {}\n", .{foo(0)});
}

Zig provides a for-loop that works only on arrays and slices.

const std = @import("std");

pub fn main() void {
    var array = [_]i32{47, 48, 49};

    for (array) | value | {
        std.debug.print("array {}\n", .{value});
    }
    for (array) | value, index | {
        std.debug.print("array {}:{}\n", .{index, value});
    }

    var slice = array[0..2];

    for (slice) | value | {
        std.debug.print("slice {}\n", .{value});
    }
    for (slice) | value, index | {
        std.debug.print("slice {}:{}\n", .{index, value});
    }
}

Zig provides a while-loop that also works as you might expect:

const std = @import("std");

pub fn main() void {
    var array = [_]i32{47, 48, 49};
    var index: u32 = 0;

    while (index < 2) {
        std.debug.print("value: {}\n", .{array[index]});
        index += 1;
    }
}

Error handling

Errors are special union types, you denote that a function can error by prepending ! to the front. You throw the error by simply returning it as if it were a normal return.

const MyError = error{
    GenericError,  // just a list of identifiers, like an enum.
    OtherError
};

pub fn main() !void {
    return MyError.GenericError;
}

If you write a function that can error, you must decide what to do with it when it returns. Two common options are try which is very lazy, and simply forwards the error to be the error for the function. catch explicitly handles the error.

• try is just sugar for catch | err | {return err}

const std = @import("std");
const MyError = error{
    GenericError
};

fn foo(v: i32) !i32 {
    if (v == 42) return MyError.GenericError;
    return v;
}

pub fn main() !void {
    // catch traps and handles errors bubbling up
    _ = foo(42) catch |err| {
        std.debug.print("error: {}\n", .{err});
    };

    // try won't get activated here.
    std.debug.print("foo: {}\n", .{try foo(47)});

    // this will ultimately cause main to print an error trace and return nonzero
    _ = try foo(42);
}

You can also use if to check for errors.

const std = @import("std");
const MyError = error{
    GenericError
};

fn foo(v: i32) !i32 {
    if (v == 42) return MyError.GenericError;
    return v;
}

// note that it is safe for wrap_foo to not have an error ! because
// we handle ALL cases and don't return errors.
fn wrap_foo(v: i32) void {    
    if (foo(v)) | value | {
        std.debug.print("value: {}\n", .{value});
    } else | err | {
        std.debug.print("error: {}\n", .{err});
    }
}

pub fn main() void {
    wrap_foo(42);
    wrap_foo(47);
}

Pointers

Pointer types are declared by prepending * to the front of the type. No spiral declarations like C! They are dereferenced, with the .* field:

const std = @import("std");

pub fn printer(value: *i32) void {
    std.debug.print("pointer: {}\n", .{value});
    std.debug.print("value: {}\n", .{value.*});
}

pub fn main() void {
    var value: i32 = 47;
    printer(&value);
}

Note:

• in Zig, pointers need to be aligned correctly with the alignment of the value it's pointing to.

For structs, similar to Java, you can dereference the pointer and get the field in one shot with the . operator. Note this only works with one level of indirection, so if you have a pointer to a pointer, you must dereference the outer pointer first.

const std = @import("std");

const MyStruct = struct {
    value: i32
};

pub fn printer(s: *MyStruct) void {
    std.debug.print("value: {}\n", .{s.value});
}

pub fn main() void {
    var value = MyStruct{.value = 47};
    printer(&value);
}

Zig allows any type (not just pointers) to be nullable, but note that they are unions of the base type and the special value null. To access the unwrapped optional type, use the .? field:

const std = @import("std");

pub fn main() void {
    var value: i32 = 47;
    var vptr: ?*i32 = &value;
    var throwaway1: ?*i32 = null;
    var throwaway2: *i32 = null; // error: expected type '*i32', found '(null)'

    std.debug.print("value: {}\n", .{vptr.*}); // error: attempt to dereference non-pointer type
    std.debug.print("value: {}\n", .{vptr.?.*});
}

Note:

• when you use pointers from C ABI functions they are automatically converted to nullable pointers.

Another way of obtaining the unwrapped optional pointer is with the if statement:

const std = @import("std");

fn nullChoice(value: ?*i32) void {
    if (value) | v | {
        std.debug.print("value: {}\n", .{v.*});
    } else {
        std.debug.print("null!\n", .{});
    }
}

pub fn main() void {
    var value: i32 = 47;
    var vptr1: ?*i32 = &value;
    var vptr2: ?*i32 = null;

    nullChoice(vptr1);
    nullChoice(vptr2);
}

A taste of metaprogramming

Zig's metaprogramming is driven by a few basic concepts:

• Types are valid values at compile-time
• most runtime code will also work at compile-time.
• struct field evaluation is compile-time duck-typed.
• the zig standard library gives you tools to perform compile-time reflection.

Here's an example of multiple dispatch (though you have already seen this in action with std.debug.print, perhaps now you can imagine how it's implemented:

const std = @import("std");

fn foo(x : anytype) @TypeOf(x) {
    // note that this if statement happens at compile-time, not runtime.
    if (@TypeOf(x) == i64) {
        return x + 2;
    } else {
        return 2 * x;
    }
}

pub fn main() void {
    var x: i64 = 47;
    var y: i32 =  47;

    std.debug.print("i64-foo: {}\n", .{foo(x)});
    std.debug.print("i32-foo: {}\n", .{foo(y)});
}

Here's an example of generic types:

const std = @import("std");

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

const V2i64 = Vec2Of(i64);
const V2f64 = Vec2Of(f64);

pub fn main() void {
    var vi = V2i64{.x = 47, .y = 47};
    var vf = V2f64{.x = 47.0, .y = 47.0};
    
    std.debug.print("i64 vector: {}\n", .{vi});
    std.debug.print("f64 vector: {}\n", .{vf});
}

From these concepts you can build very powerful generics!

The HEAP

Zig gives you many ways to interact with the heap, and usually requires you to be explicit about your choices. They all follow the same pattern:

1. Create an Allocator factory struct.
2. Retrieve the std.mem.Allocator struct creacted by the Allocator factory.
3. Use the alloc/free and create/destroy functions to manipulate the heap.
4. (optional) deinit the Allocator factory.

Whew! That sounds like a lot. But

• this is to discourage you from using the heap.
• it makes anything which calls the heap (which are fundamentally failable) obvious.
• by being unopinionated, you can carefully tune your tradeoffs and use standard datastructures without having to rewrite the standard library.
• you can run an extremely safe allocator in your tests and swap it out for a different allocator in release/prod.

Ok. But you can still be lazy. Do you miss just using jemalloc everywhere?
Just pick a global allocator and use that everywhere (being aware that some allocators are threadsafe and some allocators are not)! Please don't do this if you are writing a general purpose library.

In this example we'll use the std.heap.GeneralPurposeAllocator factory to create an allocator with a bunch of bells and whistles (including leak detection) and see how this comes together.

One last thing, this uses the defer keyword, which is a lot like go's defer keyword! There's also an errdefer keyword, but to learn more about that check the Zig docs (linked below).

const std = @import("std");

// factory type
const Gpa = std.heap.GeneralPurposeAllocator(.{});

pub fn main() !void {
    // instantiates the factory
    var gpa = Gpa{};
    
    // retrieves the created allocator.
    var galloc = &gpa.allocator;
    
    // scopes the lifetime of the allocator to this function and
    // performs cleanup; 
    defer _ = gpa.deinit();

    var slice = try galloc.alloc(i32, 2);
    // uncomment to remove memory leak warning
    // defer galloc.free(slice);
    
    var single = try galloc.create(i32);
    // defer gallo.destroy(single);

    slice[0] = 47;
    slice[1] = 48;
    single.* = 49;

    std.debug.print("slice: [{}, {}]\n", .{slice[0], slice[1]});
    std.debug.print("single: {}\n", .{single.*});
}

Coda

That's it! Now you know a fairly decent chunk of zig. Some (pretty important) things I didn't cover include:

• tests! Dear god please write tests. Zig makes it easy to do it.
• the standard library
  • the memory model (somewhat uniquely, zig is aggressively unopinionated about allocators)
• async
• cross-compilation
• build.zig

For more details, check the latest documentation: https://ziglang.org/documentation/master/

or for a less half-baked tutorial, go to: https://ziglearn.org/

@89z good point! Thank you. In fact, zig calls them tuples too, though it is an internal designation that is synonymous to anonymous structs with numbered fields. Tuples are less of a mouthful, and it's not a wrong designation, so I put it in the doc.

* I think you should add, as a comment, the output of each `print()` example.

I am purposefully leaving this out to encourage one to download zig and try them to see what happens

@ityonemo, I think people who got here are either really want to get into Zig and give them the result won't make a difference beside making your tutorial clearer. For most, it is a check up people get what they think they should get (You might surprise them, then curiosity will kick in).

* Could you explain the difference between using `fn foo(x : anytype) @TypeOf(x)` to `fn foo(comptime T, x: T) @T` for functions which supports multiple input types?

Yep! The first function takes one parameter. The second function takes two parameters, I would say that the first one is true multiple dispatch, the second one is assisted multiple dispatch. I literally just made that term up just now. So don't take it too seriously.

@ityonemo, Performance wise, are they different? Will the generated code be any different?

@RoyiAvital

Performance wise, are they different? Will the generated code be any different?

No. Comptime values only exist at comptime. Debug build: https://godbolt.org/z/qe7sjK . Release build: https://godbolt.org/z/sbePcP

    // defer gallo.destroy(single);

If I'm not mistaken, this is a typo

Indeed!

You should really open a PR to have this on https://learnxinyminutes.com

In this sentence, are has no purpose.

zig also has slices, which are have run-time known length.

Many thanks for this tutorial! I havfe translated it to Brazilian Portuguese:

https://gist.github.com/AndersonTorres/219b0cfd522d65630efc5a1e1b3ac98e

Fantastic work on the concise tutorial. I have a question concerning the code snippet for the switch statement. Your example is:

fn foo(v: i32) []const u8 {
    switch (v) {
        0 => return "zero",
        else => return "nonzero"
    }
}

As far as I understand, a slice type []T is equivalent to a pointer type [*]T with an associated length. If that is true, then you are returning a pointer to something that was allocated on the function stack memory after the function returns. Very similar to writing this in C

const char * foo() {
   return "bar";
}

which is a bad idea.

Is there a mechanism that makes this okay in Zig or is there indeed a problem?

i believe "zero" and "nonzero" are compile-time const u8 arrays (with a zero sentinel, for completeness), which means they wind up in the .data segment of your compiled binary, and thus emplaced into the memory of your program at load-time, so there is no problem. I am 90% sure that zig handles the type coercion between [ _:0] u8 and []u8

(incidentally I think C also does this in your example, but it's been a long time since I've used C "for realz", so I could be way off on that too).

Yes, this is totally fine for constant strings, both in C and Zig.

@ityonemo @jedisct1 Thanks for the explanation!

Thanks very much - just the right size of tutrorial not to get choked in!

Some typos I ran into:

error: Unused argument <-- # should be //

which are have run-time known length. <-- leave out "are"
string example (and the following examples)
std.debug.print("string {s}\n", .{string}); // <-- format specifier like s is needed
otherwise error: error: cannot format array ref without a specifier (i.e. {s} or {*})
fn wrapFoo(v: i32) void { // <-- functions should be camelCase, like wrapFoo
// defer gallo.destroy(single); <-- already mentioned, should be galloc.destroy

Thanks!

hi i don't know a lot of zig so correct me if I am wrong here but I think this sentence Enums are declared by assigning the group of enums as a type using the const keyword. should read like this Enums are declared by assigning the group of variants as a type using the const keyword unless I am wrong and an enum is actually a group of enums

hi i don't know a lot of zig so correct me if I am wrong here but I think this sentence Enums are declared by assigning the group of enums as a type using the const keyword. [...]should read like this Enums are declared by assigning the group of variants as a type using the const keyword unless I am wrong and an enum is actually a group of enums

I think when the author wrote group of enums he meant set of enumerated named values (which is how an enum is described in https://ziglearn.org/chapter-1/#enums)

I like the small language but still have the power. Not like Rust, force you to fight against compiler and force its philosophy to developers. Zig looks too intuitive and just the language is designed by you and for you. Bye Rust, Zig is my first system programming language since today.

Zig feels a lot like C, but safer. I'm not giving up on Rust yet, but this is promising.

As of January 2023, the language is very much in flux. I suggest tracking master and being prepared for code breakage.

Great summary!
I like Zig a lot and its simplicity. Still a bit in flux. Tried some multi threading but now in 0.11 it has regressed a bit.
Hope that once it stabilizes it will be a lot of fun to use.
All of the guys working on this very nice language - kudos! Keep on going.

Side comment about Rust: Its compiler its slow - yes - but super helpful. I kind of miss its suggestions while coding in Zig.
Hopefully documentation will improve in Zig.

for strings, you need to use {s} for std.debug.print(), so instead of std.debug.print("string {}\n", .{string});, you need to use std.debug.print("string {s}\n", .{string});

Also for enum, you need to specify the type now so that

const EnumType = enum{
    EnumOne,
    EnumTwo,
    EnumThree = 3
};

needs to be

const EnumType = enum(u8) {
    EnumOne,
    EnumTwo,
    EnumThree = 3
};

To get the allocator, instead of writing var galloc = &gpa.allocator; just write var galloc = gpa.allocator();

@ityonemo really nice work, translated into Simplified Chinese
中文翻译

Great tutorial, but I'm having a problem with some code I've wrote and I was hoping you could help me. I can't figure out how to take user input and print back to them as a string, do you have any idea how to.