Learning Zig

https://www.openmymind.net/learning_zig/
Admin
Learning Zig is a comprehensive introduction guide to the Zig programming language, covering...
Tokens:26,210
Snippets:316
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Full generic list implementation

Source: https://www.openmymind.net/learning_zig/generics

A complete working example of a generic list implementation.

```zig
const std = @import("std");
const Allocator = std.mem.Allocator;

pub fn main() !void {
	var gpa = std.heap.DebugAllocator(.{}){};
	const allocator = gpa.allocator();

	var list = try List(u32).init(allocator);
	defer list.deinit();

	for (0..10) |i| {
		try list.add(@intCast(i));
	}

```

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

### Configuring Executable and Test Steps in Zig Build

Source: https://www.openmymind.net/learning_zig/coding_in_zig

This snippet sets up both an executable and a test runner within the same build file. It defines dependencies for running the executable and executing tests, ensuring they are tied to the installation step.

```zig
const mod = b.createModule(.{
	.target = target,
	.optimize = optimize,
	.root_source_file = b.path("learning.zig"),
});

{
	// setup exe
	const exe = b.addExecutable(.{
			.name = "learning",
			.root_module = mod,
	});
	b.installArtifact(exe);

	const run_cmd = b.addRunArtifact(exe);
	run_cmd.step.dependOn(b.getInstallStep());
	const run_step = b.step("run", "Start learning!");
	run_step.dependOn(&run_cmd.step);
}

{
	// setup tests
	const tests = b.addTest(.{
		.root_module = mod,
	});

	const test_cmd = b.addRunArtifact(tests);
	test_cmd.step.dependOn(b.getInstallStep());
	const test_step = b.step("test", "Run the tests");
	test_step.dependOn(&test_cmd.step);
}
```

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

### Iterating with a while Loop

Source: https://www.openmymind.net/learning_zig/language_overview_2

Use a `while` loop for more control over iteration, such as manually managing the loop counter. This example shows iterating until a condition is met.

```zig
var escape_count: usize = 0;
{
	var i: usize = 0;
	while (i < src.len) {
		// backslash is used as an escape character, thus we need to escape it...

```

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

### Adding Run Command and Step to Zig Build

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Extends the build configuration to include a 'run' step. This allows you to execute the compiled program directly using `zig build run`. It depends on the installation step.

```zig
// add after: b.installArtifact(exe);

const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());

const run_step = b.step("run", "Start learning!");
run_step.dependOn(&run_cmd.step);
```

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

### Demonstrate shallow copying with nested pointers

Source: https://www.openmymind.net/learning_zig/pointers

A full example showing how a struct with a mutable slice is copied and how the underlying data can be modified via the copied pointer.

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

pub fn main() void {
	var name = [4]u8{'G', 'o', 'k', 'u'};
	const user = User{
		.id = 1,
		.power = 100,
		// slice it, [4]u8 -> []u8
		.name = name[0..],
	};
	levelUp(user);
	std.debug.print("{s}\n", .{user.name});
}

fn levelUp(user: User) void {
	user.name[2] = '!';
}

pub const User = struct {
	id: u64,
	power: i32,
	// []const u8 -> []u8
	name: []u8
};
```

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

### Zig ArrayList Example with User Data

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Illustrates the usage of std.ArrayList(User) for managing a dynamic list of User objects. It includes input handling from stdin, duplicating strings for ownership, and proper deinitialization of both individual users and the ArrayList itself.

```zig
const std = @import("std");
const builtin = @import("builtin");
const Allocator = std.mem.Allocator;

pub fn main() !void {
  var gpa: std.heap.DebugAllocator(.{}) = .init;
  const allocator = gpa.allocator();

  var arr: std.ArrayList(User) = .empty;
  defer {
    for (arr.items) |user| {
      user.deinit(allocator);
    }
    arr.deinit(allocator);
  }

  var buf: [30]u8 = undefined;
  var stdin = std.fs.File.stdin().reader(&buf);
  var stdout = std.fs.File.stdout().writer(&.{});

  var i: i32 = 0;
  while (true) : (i += 1) {
    try stdout.interface.print("Please enter a name: ", .{
    });
    var name = try stdin.interface.takeDelimiterExclusive('\n');
    stdin.interface.toss(1); // discard the delimiter

    if (builtin.os.tag == .windows) {
      // In Windows lines are terminated by \r\n.
      // We need to strip out the \r
      name = std.mem.trimRight(u8, name, "\r");
    }
    if (name.len == 0) {
      break;
    }
    const owned_name = try allocator.dupe(u8, name);
    try arr.append(allocator, .{.name = owned_name, .power = i});
  }

  var has_leto = false;
  for (arr.items) |user| {
    if (std.mem.eql(u8, "Leto", user.name)) {
      has_leto = true;
      break;
    }
  }

  std.debug.print("{any}\n", .{has_leto});
}

const User = struct {
  name: []const u8,
  power: i32,

  fn deinit(self: User, allocator: Allocator) void {
    allocator.free(self.name);
  }
};

```

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

### Partial build.zig modification

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Snippet showing the start of a modification to build.zig for remote dependencies.

```zig
// replace this:
const calc_module = b.createModule("calc", .{
```

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

### Zig Test Case Example

Source: https://www.openmymind.net/learning_zig/coding_in_zig

A simple test case written in Zig. This test is designed to fail, demonstrating how to use `std.testing.expectEqual` to assert conditions within tests.

```zig
test "dummy build test" {
	try std.testing.expectEqual(false, true);
}
```

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

### Zig Build Hash Mismatch Error

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Example of a hash mismatch error encountered during `zig build test`. This indicates a discrepancy between the declared and fetched package hashes.

```text
hash mismatch: manifest declares
122053da05e0c9348d91218ef015c8307749ef39f8e90c208a186e5f444e818672da

but the fetched package has
122036b1948caa15c2c9054286b3057877f7b152a5102c9262511bf89554dc836ee5
```

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

### Dangling pointer example

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates an invalid pattern where a function returns a pointer to a local stack variable.

```zig
pub const User = struct {
	fn init(id: u64, power: i32) *User{
		var user = User{
			.id = id,
			.power = power,
		};
		// this is a dangling pointer
		return &user;
	}
};
```

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

### Zig User Struct and Level Up Function

Source: https://www.openmymind.net/learning_zig/pointers

Demonstrates a basic Zig struct and a function that attempts to modify a struct field. This example highlights Zig's pass-by-value for structs and parameter immutability.

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

pub fn main() void {
	var user = User{
		.id = 1,
		.power = 100,
	};

	// this line has been added
	levelUp(user);
	std.debug.print("User {d} has power of {d}\n", .{user.id, user.power});
}

fn levelUp(user: User) void {
	user.power += 1;
}

pub const User = struct {
	id: u64,
	power: i32,
};

```

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

### Valid Recursive Struct using Pointers

Source: https://www.openmymind.net/learning_zig/pointers

This example shows how to correctly implement a recursive structure by using a pointer to the type, ensuring a fixed size at compile time.

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

pub fn main() void {
	const leto = User{
		.id = 1,
		.power = 9001,
		.manager = null,
	};

	const duncan = User{
		.id = 1,
		.power = 9001,
		// changed from leto -> &leto
		.manager = &leto,
	};

	std.debug.print("{any}\n{any}", .{leto, duncan});
}

pub const User = struct {
	id: u64,
	power: i32,
	// changed from ?const User -> ?*const User
	manager: ?*const User,
};
```

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

### Zig Labeled For Loop with Continue

Source: https://www.openmymind.net/learning_zig/language_overview_2

Illustrates Zig's labeled blocks and the use of `continue` to target a specific outer loop. This example skips to the next iteration of the `outer` loop when the condition `i * j > (i+i + j+j)` is met.

```zig
outer: for (1..10) |i| {
	for (i..10) |j| {
		if (i * j > (i+i + j+j)) continue :outer;
		std.debug.print("{d} + {d} >= {d} * {d}\n", .{i+i, j+j, i, j});
	}
}
```

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

### Demonstrate Dangling Pointer via StringHashMap

Source: https://www.openmymind.net/learning_zig/coding_in_zig

This example shows how calling remove on a StringHashMap invalidates a pointer previously retrieved by getPtr, leading to undefined behavior.

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

pub fn main() !void {
	var gpa = std.heap.DebugAllocator(.{}){};
	const allocator = gpa.allocator();

	var lookup = std.StringHashMap(User).init(allocator);
	defer lookup.deinit();

	const goku = User{.power = 9001};

	try lookup.put("Goku", goku);

	// returns an optional, .? would panic if "Goku"
	// wasn't in our hashmap
	const entry = lookup.getPtr("Goku").?;

	std.debug.print("Goku's power is: {d}\n", .{entry.power});

	// returns true/false depending on if the item was removed
	_ = lookup.remove("Goku");

	std.debug.print("Goku's power is: {d}\n", .{entry.power});
}

const User = struct {
	power: i32,
};
```

```text
Goku's power is: 9001
Goku's power is: -1431655766
```

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

### Calling Logger Info with Incorrect Type

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Example of attempting to call the logger's info function with a boolean, which lacks a 'writeAll' method, resulting in a compile-time error.

```zig
var l = Logger{.level = .info};
try l.info("server started", true);

```

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

### Zig Memory Leak Example

Source: https://www.openmymind.net/learning_zig/heap_memory

This code demonstrates a memory leak by allocating memory in `allocLower` but never freeing it. Once the `isSpecial` function returns, the reference to the allocated memory is lost, making it impossible to free.

```zig
// For this specific code, we should have used std.ascii.eqlIgnoreCase
fn isSpecial(allocator: Allocator, name: [] const u8) !bool {
	const lower = try allocLower(allocator, name);
	return std.mem.eql(u8, lower, "admin");
}
```

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

### Zig Variable Referencing Type Example

Source: https://www.openmymind.net/learning_zig/style_guide

This Zig code shows how a variable (`T`) assigned the result of a type-returning function (`@TypeOf`) should follow the type naming convention (PascalCase).

```zig
const T = @TypeOf(3)
std.debug.print("{any}\n", .{T});
```

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

### Initialize Arrays with Different Syntax

Source: https://www.openmymind.net/learning_zig/language_overview_1

Demonstrates various ways to define fixed-size arrays, including explicit typing and compiler inference.

```zig
const a = [5]i32{1, 2, 3, 4, 5};

// we already saw this .{...} syntax with structs
// it works with arrays too
const b: [5]i32 = .{1, 2, 3, 4, 5};

// use _ to let the compiler infer the length
const c = [_]i32{1, 2, 3, 4, 5};
```

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

### Zig Type Naming Convention Example

Source: https://www.openmymind.net/learning_zig/style_guide

This Zig code snippet demonstrates the PascalCase naming convention for types and variables referencing types. It uses `@TypeOf` to get the type of a struct literal and prints it.

```zig
std.debug.print("{any}\n", .{@TypeOf(.{.year = 2023, .month = 8})});
```

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

### Setting up an Executable in Zig Build

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Configure the build system to compile an executable. This snippet sets up standard target and optimization options and defines the root module and source file for the executable.

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

pub fn build(b: *std.Build) !void {
	const target = b.standardTargetOptions(.{});
	const optimize = b.standardOptimizeOption(.{});

	// setup executable
	const exe = b.addExecutable(.{
		.name = "learning",
		.root_module = b.createModule(.{
			.target = target,
			.optimize = optimize,
			.root_source_file = b.path("learning.zig"),
		}),
	});
	b.installArtifact(exe);
}
```

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

### Initialize a struct

Source: https://www.openmymind.net/learning_zig/language_overview_1

Creates a new instance of the User struct.

```zig
const user = User{.name = "Goku"};
```

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

### Invalid Recursive Struct Definition

Source: https://www.openmymind.net/learning_zig/pointers

This example demonstrates a failed attempt at creating a recursive struct, which results in a compile-time error due to unknown size.

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

pub fn main() void {
	const leto = User{
		.id = 1,
		.power = 9001,
		.manager = null,
	};

	const duncan = User{
		.id = 1,
		.power = 9001,
		.manager = leto,
	};

	std.debug.print("{any}\n{any}", .{leto, duncan});
}

pub const User = struct {
	id: u64,
	power: i32,
	manager: ?User,
};
```

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

### Basic Zig Program Structure

Source: https://www.openmymind.net/learning_zig/language_overview_1

Demonstrates a simple Zig program with a main function, a struct definition, and printing output to the console. Ensure the `main` function is `pub` for execution.

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

// This code won't compile if `main` isn't `pub` (public)
pub fn main() void {
	const user = User{
		.power = 9001,
		.name = "Goku",
	};

	std.debug.print("{s}'s power is {d}\n", .{user.name, user.power});
}

pub const User = struct {
	power: u64,
	name: []const u8,
};

```

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

### Initialize DebugAllocator for HTTP Server

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates creating a thread-safe DebugAllocator and passing it to an HTTP server instance.

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

pub fn fn main() !void {
	// create our general purpose allocator
	var gpa = std.heap.DebugAllocator(.{}){};

	// get an std.mem.Allocator from it
	const allocator = gpa.allocator();

	// pass our allocator to functions and libraries that require it
	var server = try httpz.Server().init(allocator, .{.port = 5882});

	var router = server.router();
	router.get("/api/user/:id", getUser);

	// blocks the current thread
	try server.listen();
}
```

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

### Define the main entry point

Source: https://www.openmymind.net/learning_zig/language_overview_1

The main function serves as the entry point for every executable Zig program.

```zig
pub fn main() void
```

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

### Call struct methods

Source: https://www.openmymind.net/learning_zig/language_overview_1

Demonstrates dot syntax and explicit function calls for struct methods.

```zig
// call diagnose on user
user.diagnose();

// The above is syntactical sugar for:
User.diagnose(user);
```

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

### Basic Zig Build File Skeleton

Source: https://www.openmymind.net/learning_zig/coding_in_zig

This is the minimal structure for a `build.zig` file. It imports the standard library and defines the main `build` function.

```zig
// build.zig

const std = @import("std");

pub fn build(b: *std.Build) !void {
	_ = b;
}
```

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

### Configure build.zig for local package

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Standard build configuration for testing a local package.

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

pub fn build(b: *std.Build) !void {
	const target = b.standardTargetOptions(.{});
	const optimize = b.standardOptimizeOption(.{});

	const tests = b.addTest(.{
		.root_module = b.addModule(.{
			.target = target,
			.optimize = optimize,
			.root_source_file = b.path("calc.zig"),
		});
	});

	const test_cmd = b.addRunArtifact(tests);
	test_cmd.step.dependOn(b.getInstallStep());
	const test_step = b.step("test", "Run the tests");
	test_step.dependOn(&test_cmd.step);
}
```

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

### Using ArenaAllocator with IntList

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates wrapping an allocator with an ArenaAllocator to manage the lifetime of an IntList.

```zig
var gpa = std.heap.DebugAllocator(.{}){};
const allocator = gpa.allocator();

var arena = std.heap.ArenaAllocator.init(allocator);
defer arena.deinit();
const aa = arena.allocator();

var list = try IntList.init(aa);

// I'm honestly torn on whether or not we should call list.deinit.
// Technically, we don't have to since we call defer arena.deinit() above.
defer list.deinit();

...
```

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

### Initialize and Use FixedBufferAllocator in Zig

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates initializing a FixedBufferAllocator with a buffer, allocating memory for JSON stringification, and freeing it. The `defer fa.reset()` ensures all memory is freed when the function exits. Be mindful of buffer size to avoid OutOfMemory errors.

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

pub fn main() !void {
	var buf: [150]u8 = undefined;
	var fa = std.heap.FixedBufferAllocator.init(&buf);

	// this will free all memory allocate with this allocator
	defer fa.reset();

	const allocator = fa.allocator();

	const json = try std.json.Stringify.valueAlloc(allocator, .{
		.this_is = "an anonymous struct",
		.above = true,
		.last_param = "are options",
	}, .{.whitespace = .indent_2});

	// We can free this allocation, but since we know that our allocator is
	// a FixedBufferAllocator, we can rely on the above `defer fa.reset()`
	defer allocator.free(json);

	std.debug.print("{s}\n", .{json});
}

```

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

### Zig main function using IntList

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates the usage of the IntList struct in a main function, initializing it with a DebugAllocator, adding elements, and printing the resulting array. Ensure to deinitialize the list to prevent memory leaks.

```zig
const std = @import("std");
const Allocator = std.mem.Allocator;

pub fn main() !void {
	var gpa = std.heap.DebugAllocator(.{}){};
	const allocator = gpa.allocator();

	var list = try IntList.init(allocator);
	defer list.deinit();

	for (0..10) |i| {
		try list.add(@intCast(i));
	}

	std.debug.print("{any}\n", .{list.items[0..list.pos]});
}
```

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

### Zig Shadowing Error Example

Source: https://www.openmymind.net/learning_zig/style_guide

This Zig code illustrates a shadowing error where a variable name (`read`) conflicts with a function name (`read`). To fix this, rename the variable to something distinct, like `n`.

```zig
fn read(stream: std.net.Stream) ![]const u8 {
	var buf: [512]u8 = undefined;
	const read = try stream.read(&buf);
	if (read == 0) {
		return error.Closed;
	}
	return buf[0..read];
}
```

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

### Define calc.zig module entry point

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Exposes the add function and ensures all nested declarations are tested.

```zig
pub const add = @import("add.zig").add;

test {
	// By default, only tests in the specified file
	// are included. This magic line of code will
	// cause a reference to all nested containers
	// to be tested.
	@import("std").testing.refAllDecls(@This());
}
```

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

### Manual Memory Management in a Parser

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates the standard approach of manually freeing individual allocations using defer.

```zig
fn parse(allocator: Allocator, input: []const u8) !Something {
	const buf = try allocator.alloc(u8, 512);
	defer allocator.free(buf);

	const nesting = try allocator.alloc(NestType, 10)
	defer allocator.free(nesting);

	const state = State{
		.buf = buf,
		.nesting = nesting,
	};

	return parseInternal(allocator, state, input);
}
```

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

### Calling Logger Info with Correct Type

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Demonstrates successfully calling the logger's info function by passing a writer interface that implements the 'writeAll' method.

```zig
pub fn main() !void {
    var l = Logger{.level = .info};
    var writer = std.fs.File.stdout().writer(&.{});
    try l.info("sever started", &writer.interface);
}

```

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

### Standard DebugAllocator Initialization

Source: https://www.openmymind.net/learning_zig/heap_memory

Initializes a DebugAllocator for general purpose memory management.

```zig
var gpa = std.heap.DebugAllocator(.{}){};
const allocator = gpa.allocator();

var list = try IntList.init(allocator);
defer list.deinit();
```

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

### Implementing std.mem.eql

Source: https://www.openmymind.net/learning_zig/language_overview_2

This is a simplified implementation of `std.mem.eql`, demonstrating slice comparison. It first checks lengths and then iterates through elements.

```zig
pub fn eql(comptime T: type, a: []const T, b: []const T) bool {
	// if they aren't the same length, they can't be equal
	if (a.len != b.len) return false;

	for (a, b) |a_elem, b_elem| {
		if (a_elem != b_elem) return false;
	}

	return true;
}
```

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

### Allocate a string with std.fmt.allocPrint

Source: https://www.openmymind.net/learning_zig/heap_memory

Use allocPrint to allocate and return a formatted string, ensuring the caller manages the memory with free.

```zig
const say = std.fmt.allocPrint(allocator, "It's over {d}!!!", .{user.power});
defer allocator.free(say);
```

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

### Importing Multiple Definitions

Source: https://www.openmymind.net/learning_zig/language_overview_1

Illustrates importing multiple definitions, including a struct and a constant, from a single file. The imported definitions are accessed as properties of the imported module.

```zig
// models/user.zig
pub const MAX_POWER = 100_000;

pub const User = struct {
	power: u64,
	name: []const u8,
};

```

```zig
const user = @import("models/user.zig");
const User = user.User;
const MAX_POWER = user.MAX_POWER;

```

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

### Create local module dependency

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Defines a module pointing to a local path for use in build.zig.

```zig
// You can put this near the top of the build
// function, before the call to addExecutable.

const calc_module = b.createModule("calc", .{
	.root_source_file = b.path("PATH_TO_CALC_PROJECT/calc.zig"),
});
```

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

### Integrate local module into build.zig

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Shows how to include a local module in the project's main module imports.

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

pub fn build(b: *std.Build) !void {
	const target = b.standardTargetOptions(.{});
	const optimize = b.standardOptimizeOption(.{});

	const calc_module = b.createModule("calc", .{
		.root_source_file = b.path("PATH_TO_CALC_PROJECT/calc.zig"),
	});

	const mod = b.createModule(.{
		.target = target,
		.optimize = optimize,
		.root_source_file = b.path("learning.zig"),
		.imports = &.{
			.{.name = "calc", .module = calc_module},
		}
	});

	// setup our exe and test like before
}
```

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

### Instantiate a generic type

Source: https://www.openmymind.net/learning_zig/generics

Syntax for creating an instance of a generic type.

```zig
var list = try List(u32).init(allocator);
```

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

### Populate StringHashMap with User input

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Initial implementation that demonstrates a lifetime issue by using a stack-allocated buffer as a hash map key.

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

pub fn main() !void {
  var gpa = std.heap.GeneralPurposeAllocator(.{}){};
  const allocator = gpa.allocator();

  var lookup = std.StringHashMap(User).init(allocator);
  defer lookup.deinit();

  var buf: [30]u8 = undefined;
  var stdin = std.fs.File.stdin().reader(&buf);

  var stdout = std.fs.File.stdout().writer(&.{});

  var i: i32 = 0;
  while (true) : (i += 1) {
    try stdout.interface.print("Please enter a name: ", .{});
    var name = try stdin.interface.takeDelimiterExclusive('\n');
    stdin.interface.toss(1); // discard the delimiter

    if (builtin.os.tag == .windows) {
      // In Windows lines are terminated by \r\n.
      // We need to strip out the \r
      name = @constCast(std.mem.trimRight(u8, name, "\r"));
    }
    if (name.len == 0) {
      break;
    }
    try lookup.put(name, .{.power = i});
  }

  const has_leto = lookup.contains("Leto");
  std.debug.print("{any}\n", .{has_leto});
}

const User = struct {
  power: i32,
};
```

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

### Allocate and manage a struct on the heap

Source: https://www.openmymind.net/learning_zig/heap_memory

Uses allocator.create to allocate a single User struct on the heap and allocator.destroy to free it.

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

pub fn main() !void {
	// again, we'll talk about allocators soon!
	var gpa = std.heap.DebugAllocator(.{}){};
	const allocator = gpa.allocator();

	// create a User on the heap
	var user = try allocator.create(User);

	// free the memory allocated for the user at the end of this scope
	defer allocator.destroy(user);

	user.id = 1;
	user.power = 100;

	// this line has been added
	levelUp(user);
	std.debug.print("User {d} has power of {d}\n", .{user.id, user.power});
}

fn levelUp(user: *User) void {
	user.power += 1;
}

pub const User = struct {
	id: u64,
	power: i32,
};
```

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

### Define a basic struct

Source: https://www.openmymind.net/learning_zig/language_overview_1

Defines a simple User struct with power and name fields.

```zig
pub const User = struct {
	power: u64,
	name: []const u8,
};
```

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

### Importing a Local Struct

Source: https://www.openmymind.net/learning_zig/language_overview_1

Shows how to import a `User` struct defined in a separate file (`models/user.zig`). The struct must be marked `pub` in its own file to be importable.

```zig
// models/user.zig
pub const User = struct {
	power: u64,
	name: []const u8,
};

```

```zig
// main.zig
const User = @import("models/user.zig").User;

```

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

### Define build.zig.zon for remote dependency

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Configuration file for managing remote dependencies via URL and hash.

```zig
.{
  .name = .learning,
  .paths = .{"
```

```zig
  .version = "0.0.0",
  .dependencies = .{
    .calc = .{
      .url = "https://github.com/karlseguin/calc.zig/archive/d1881b689817264a5644b4d6928c73df8cf2b193.tar.gz",
      .hash = "12ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
    },
  },
}
```

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

### Define print function with comptime and anytype

Source: https://www.openmymind.net/learning_zig/language_overview_1

The function signature for print, demonstrating the use of comptime for format validation and anytype for variadic-like argument handling.

```zig
// notice the "comptime" before the "fmt" variable
pub fn print(comptime fmt: []const u8, args: anytype) void {
```

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

### Create a basic generic array with comptime length

Source: https://www.openmymind.net/learning_zig/generics

Demonstrates a function returning a type based on a compile-time known length parameter.

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

pub fn main() !void {
	var arr: IntArray(3) = undefined;
	arr[0] = 1;
	arr[1] = 10;
	arr[2] = 100;
	std.debug.print("{any}\n", .{arr});
}

fn IntArray(comptime length: usize) type {
	return [length]i64;
}
```

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

### Initialize with type inference

Source: https://www.openmymind.net/learning_zig/language_overview_1

Uses the dot-brace syntax for struct initialization when the type is known.

```zig
const user: User = .{
	.power = 9001,
	.name = "Goku",
};
```

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

### Initialize DebugAllocator with Declaration Literals

Source: https://www.openmymind.net/learning_zig/heap_memory

Uses declaration literals to improve readability when initializing the allocator.

```zig
var gpa: std.heap.DebugAllocator(.{}) = .init;
```

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

### Zig List Initialization and Deinitialization

Source: https://www.openmymind.net/learning_zig/generics

Initializes a generic list with a given allocator and frees its allocated memory. Ensure the allocator is valid.

```zig
fn init(allocator: Allocator) !List(T) {
			return .{
				.pos = 0,
				.allocator = allocator,
				.items = try allocator.alloc(T, 4),
			};
		}

		fn deinit(self: List(T)) void {
			self.allocator.free(self.items);
		}
```

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

### Define a struct with methods and constants

Source: https://www.openmymind.net/learning_zig/language_overview_1

Includes a constant and a method within the struct definition.

```zig
pub const User = struct {
	power: u64 = 0,
	name: []const u8,

	pub const SUPER_POWER = 9000;

	pub fn diagnose(user: User) void {
		if (user.power >= SUPER_POWER) {
			std.debug.print("it's over {d}!!!", .{SUPER_POWER});
		}
	}
};
```

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

### DebugAllocator Initialization Syntax Variants

Source: https://www.openmymind.net/learning_zig/heap_memory

Compares explicit type assignment with the shorthand combined initialization syntax.

```zig
const T = std.heap.DebugAllocator(.{});
var gpa = T{};

// is the same as:

var gpa = std.heap.DebugAllocator(.{}){};
```

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

### Declare a constant struct instance

Source: https://www.openmymind.net/learning_zig/language_overview_1

Initializes a struct instance as a constant.

```zig
const user = User{
	.power = 9001,
	.name = "Goku",
};
```

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

### Using bufPrint for String Formatting in Zig

Source: https://www.openmymind.net/learning_zig/heap_memory

Formats a string into a pre-allocated buffer, returning an error if the buffer is too small. Useful when buffer size is known.

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

pub fn main() !void {
	const name = "Leto";

	var buf: [100]u8 = undefined;
	const greeting = try std.fmt.bufPrint(&buf, "Hello {s}", .{name});

	std.debug.print("{s}\n", .{greeting});
}
```

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

### Visualize Call Stack Memory Layout

Source: https://www.openmymind.net/learning_zig/stack_memory

A visual representation of the memory layout for main and levelUp functions on the call stack.

```text
main: user ->    -------------  (id: 1043368d0)
                 |     1     |
                 -------------  (power: 1043368d8)
                 |    100    |
                 -------------  (name.len: 1043368dc)
                 |     4     |
                 -------------  (name.ptr: 1043368e4)
                 | 1182145c0 |-------------------------
levelUp: user -> -------------  (id: 1043368ec)       |
                 |     1     |                        |
                 -------------  (power: 1043368f4)    |
                 |    100    |                        |
                 -------------  (name.len: 1043368f8) |
                 |     4     |                        |
                 -------------  (name.ptr: 104336900) |
                 | 1182145c0 |-------------------------
                 -------------                        |
                                                      |
                 .............  empty space           |
                 .............  or other data         |
                                                      |
                 -------------  (1182145c0)        <---
                 |    'G'    |
                 -------------
                 |    'o'    |
                 -------------
                 |    'k'    |
                 -------------
                 |    'u'    |
                 -------------
```

```text
main: user ->    -------------  (id: 1043368d0)
                 |     1     |
                 -------------  (power: 1043368d8)
                 |    100    |
                 -------------  (name.len: 1043368dc)
                 |     4     |
                 -------------  (name.ptr: 1043368e4)
                 | 1182145c0 |-------------------------
                 -------------
                                                      |
                 .............  empty space           |
                 .............  or other data         |
                                                      |
                 -------------  (1182145c0)        <---
                 |    'G'    |
                 -------------
                 |    'o'    |
                 -------------
                 |    'k'    |
                 -------------
                 |    'u'    |
                 -------------
```

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

### Demonstrate parameter immutability

Source: https://www.openmymind.net/learning_zig/language_overview_1

Function parameters in Zig are constants and cannot be reassigned.

```zig
fn add(a: i64, b: i64) i64 {
	a += b;
	return a;
}
```

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

### Define an init function

Source: https://www.openmymind.net/learning_zig/language_overview_1

Uses a conventional init function to construct a struct instance.

```zig
pub const User = struct {
	power: u64 = 0,
	name: []const u8,

	pub fn init(name: []const u8, power: u64) User {
		return User{
			.name = name,
			.power = power,
		};
	}
}
```

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

### Inspect Pointer Types

Source: https://www.openmymind.net/learning_zig/pointers

Demonstrates how to determine the type of a pointer using @TypeOf.

```zig
pub fn main() void {
	var user = User{
		.id = 1,
		.power = 100,
	};
	user.power += 0;

	const user_p = &user;
	std.debug.print("{any}\n", .{@TypeOf(user_p)});
}
```

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

### Expose module for remote consumption

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Explicitly define a module in the library's build.zig to allow external imports.

```zig
_ = b.addModule("calc", .{
	.root_source_file =  b.path("calc.zig"),
});
```

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

### Defining arrays with sentinel values

Source: https://www.openmymind.net/learning_zig/language_overview_1

Shows the syntax for creating an array with a specific sentinel value, which is useful for C interoperability.

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

pub fn main() void {
	// an array of 3 booleans with false as the sentinel value
	const a = [3:false]bool{false, true, false};

	// This line is more advanced, and is not going to get explained!
	std.debug.print("{any}\n", .{std.mem.asBytes(&a).*});
}
```

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

### Demonstrate Pass-by-Value Behavior

Source: https://www.openmymind.net/learning_zig/pointers

Shows that passing a struct to a function creates a copy, resulting in different memory addresses.

```zig
pub fn main() void {
	var user = User{
		.id = 1,
		.power = 100,
	};
	user.power += 0;

	// added this
	std.debug.print("main: {*}\n", .{&user});

	levelUp(user);
	std.debug.print("User {d} has power of {d}\n", .{user.id, user.power});
}

fn levelUp(user: User) void {
	// add this
	std.debug.print("levelUp: {*}\n", .{&user});
	var u = user;
	u.power += 1;
}
```

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

### Placeholder for custom deinit logic

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Indicates where to replace the default deinit call to handle manual memory cleanup for owned keys.

```zig
// replace the existing:
//   defer lookup.deinit();
// with:
```

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

### Dynamic Array Allocation and Deallocation in Zig

Source: https://www.openmymind.net/learning_zig/heap_memory

Demonstrates allocating a dynamically sized array on the heap using an allocator and freeing it. The `alloc` method returns a slice of the specified type and count, while `free` releases the allocated memory. This pattern is common for managing heap-allocated data.

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

pub fn main() !void {
	// we'll be talking about allocators shortly
	var gpa = std.heap.DebugAllocator(.{}){};
	const allocator = gpa.allocator();

	// ** The next two lines are the important ones **
	var arr = try allocator.alloc(usize, try getRandomCount());
	defer allocator.free(arr);

	for (0..arr.len) |i| {
		arr[i] = i;
	}
	std.debug.print("{any}\n", .{arr});
}

fn getRandomCount() !u8 {
	var seed: u64 = undefined;
	try std.posix.getrandom(std.mem.asBytes(&seed));
	var random = std.Random.DefaultPrng.init(seed);
	return random.random().uintAtMost(u8, 5) + 5;
}
```

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

### Zig Defer Block for Resource Cleanup

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Demonstrates a defer block used to iterate through keys, free allocated memory for each key, and then deinitialize a lookup structure. This pattern is crucial for preventing memory leaks in Zig.

```zig
defer {
	var it = lookup.keyIterator();
	while (it.next()) |key| {
		allocator.free(key.*);
	}
	lookup.deinit();
}
```

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

### Zig Logger with Anytype

Source: https://www.openmymind.net/learning_zig/coding_in_zig

A simple logger struct demonstrating 'anytype' for the output parameter, allowing it to write to any type with a 'writeAll' method. Compile-time checks ensure type compatibility.

```zig
pub const Logger = struct {
	level: Level,

	// "error" is reserved, names inside an @"..." are always
	// treated as identifiers
	const Level = enum {
		debug,
		info,
		@"error",
		fatal,
	};

	fn info(logger: Logger, msg: []const u8, out: anytype) !void {
		if (@intFromEnum(logger.level) <= @intFromEnum(Level.info)) {
			try out.writeAll(msg);
		}
	}
};

```

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

### ArenaAllocator Usage in a Parser

Source: https://www.openmymind.net/learning_zig/heap_memory

Shows how to use ArenaAllocator to manage multiple short-lived allocations that are freed simultaneously.

```zig
fn parse(allocator: Allocator, input: []const u8) !Something {
	// create an ArenaAllocator from the supplied allocator
	var arena = std.heap.ArenaAllocator.init(allocator);

	// this will free anything created from this arena
	defer arena.deinit();

	// create an std.mem.Allocator from the arena, this will be
	// the allocator we'll use internally
	const aa = arena.allocator();

	const state = State{
		// we're using aa here!
		.buf = try aa.alloc(u8, 512),

		// we're using aa here!
		.nesting = try aa.alloc(NestType, 10),
	};

	// we're passing aa here, so we're guaranteed that
	// any other allocation will be in our arena
	return parseInternal(aa, state, input);
}
```

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

### Slice an Array

Source: https://www.openmymind.net/learning_zig/language_overview_1

Shows basic array slicing syntax. Note that slicing with compile-time constants results in a pointer to an array rather than a slice.

```zig
const a = [_]i32{1, 2, 3, 4, 5};
const b = a[1..4];
```

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

### Case-Insensitive String Comparison

Source: https://www.openmymind.net/learning_zig/language_overview_2

For case-insensitive string comparisons, use `std.ascii.eqlIgnoreCase`.

```zig
std.ascii.eqlIgnoreCase(str1, str2)
```

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

### Transfer key ownership with allocator.dupe

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Fixes the lifetime issue by duplicating the key onto the heap, ensuring it outlives the hash map.

```zig
// replace the existing lookup.put with these two lines
const owned_name = try allocator.dupe(u8, name);

// name -> owned_name
try lookup.put(owned_name, .{.power = i});
```

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

### Switch with Combined Cases and Ranges

Source: https://www.openmymind.net/learning_zig/language_overview_2

Combine multiple cases or use ranges in `switch` statements. Blocks can be used for complex logic within a case.

```zig
fn arrivalTimeDesc(minutes: u16, is_late: bool) []const u8 {
	switch (minutes) {
		0 => return "arrived",
		1, 2 => return "soon",
		3...5 => return "no more than 5 minutes",
		else => {
			if (!is_late) {
				return "sorry, it'll be a while";
			}
			// todo, something is very wrong
			return "never";
		},
	}
}
```

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

### Import local module in source code

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Usage of the imported module within Zig source files.

```zig
const calc = @import("calc");
...
calc.add(1, 2);
```

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

### Create a Slice with Runtime Bounds

Source: https://www.openmymind.net/learning_zig/language_overview_1

Uses a runtime-known variable to define the slice end, ensuring the result is a proper slice type.

```zig
const a = [_]i32{1, 2, 3, 4, 5};

// because `end` is declared var, it isn't compiled-time known
var end: usize = 3;

// but because it's a `var` we need to mutate it, else the compiler
// will insist we make it `const`.
end += 1;

const b = a[1..end];
```

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

### Single-Line Comment

Source: https://www.openmymind.net/learning_zig/language_overview_1

Zig uses `//` for single-line comments. This is a standard comment format for explaining code.

```zig
// This code won't compile if `main` isn't `pub` (public)

```

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

### Implement a basic function

Source: https://www.openmymind.net/learning_zig/language_overview_1

Zig does not require forward declarations, allowing functions to be called before they are defined.

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

pub fn main() void {
	const sum = add(8999, 2);
	std.debug.print("8999 + 2 = {d}\n", .{sum});
}

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

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

### Printing Pointer Information in Zig

Source: https://www.openmymind.net/learning_zig/pointers

This snippet demonstrates how to print the address of a pointer variable and the address it points to within a function. It's useful for understanding memory layout and how pointers are passed.

```zig
fn levelUp(user: *User) void {
	std.debug.print("{*}\n{*}\n", .{&user, user});
	user.power += 1;
}
```

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

### String Comparison with std.mem.eql

Source: https://www.openmymind.net/learning_zig/language_overview_2

Use `std.mem.eql` for byte-by-byte comparison of slices, including strings. It is case-sensitive and requires specifying the element type.

```zig
if (std.mem.eql(u8, method, "GET") or std.mem.eql(u8, method, "HEAD")) {
	// handle a GET request
} else if (std.mem.eql(u8, method, "POST")) {
	// handle a POST request
} else {
	// ...
}
```

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

### Define a struct with default values

Source: https://www.openmymind.net/learning_zig/language_overview_1

Defines a User struct where the power field defaults to 0.

```zig
pub const User = struct {
	power: u64 = 0,
	name: []const u8,
};
```

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

### Add methods to a generic struct

Source: https://www.openmymind.net/learning_zig/generics

Demonstrates defining methods within a struct returned by a generic function.

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

pub fn main() !void {
	var arr = IntArray(3).init();
	arr.items[0] = 1;
	arr.items[1] = 10;
	arr.items[2] = 100;
	std.debug.print("{any}\n", .{arr.items});
}

fn IntArray(comptime length: usize) type {
	return struct {
		items: [length]i64,

		fn init() IntArray(length) {
			return .{
				.items = undefined,
			};
		}
	};
}
```

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

### Zig User Initialization with Dangling Pointer

Source: https://www.openmymind.net/learning_zig/stack_memory

This Zig code demonstrates a dangling pointer issue. The `User.init` function returns a pointer to a local variable, which becomes invalid after the function returns.

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

pub fn main() void {
	const user1 = User.init(1, 10);
	const user2 = User.init(2, 20);

	std.debug.print("User {d} has power of {d}\n", .{user1.id, user1.power});
	std.debug.print("User {d} has power of {d}\n", .{user2.id, user2.power});
}

pub const User = struct {
	id: u64,
	power: i32,

	fn init(id: u64, power: i32) *User{
		var user = User{
			.id = id,
			.power = power,
		};
		return &user;
	}
};

```

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

### Define a User struct with a slice

Source: https://www.openmymind.net/learning_zig/pointers

A basic struct definition containing an integer and a slice of bytes.

```zig
pub const User = struct {
	id: u64,
	power: i32,
	name: []const u8,
};
```

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

### Declare Zig Build Dependency

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Declare a dependency in `build.zig` using `b.dependency`. This is used to link external projects into your build.

```zig
const calc_dep = b.dependency("calc", .{.target = target, .optimize = optimize});
const calc_module = calc_dep.module("calc");
```

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

### Zig User Factory with Anytype, TypeOf, and HasField

Source: https://www.openmymind.net/learning_zig/coding_in_zig

A factory function that creates a User struct, using 'anytype' for flexible input and 'TypeOf' with '@hasField' to conditionally set fields based on the provided data. Defaults are used if fields are missing.

```zig
fn userFactory(data: anytype) User {
	const T = @TypeOf(data);
	return .{ 
		.id = if (@hasField(T, "id")) data.id else 0,
		.power = if (@hasField(T, "power")) data.power else 0,
		.active  = if (@hasField(T, "active")) data.active else true,
		.name  = if (@hasField(T, "name")) data.name else "",
	};
}

pub const User = struct {
	id: u64,
	power: u64,
	active: bool,
	name: [] const u8,
};

```

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

### Define add function in add.zig

Source: https://www.openmymind.net/learning_zig/coding_in_zig

Implements a generic add function and a corresponding unit test.

```zig
// Oh, a hidden lesson, look at the type of b
// and the return type!!

pub fn add(a: anytype, b: @TypeOf(a)) @TypeOf(a) {
	return a + b;
}

const testing = @import("std").testing;
test "add" {
	try testing.expectEqual(32, add(30, 2));
}
```

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

### Print formatted output in Zig

Source: https://www.openmymind.net/learning_zig/language_overview_1

Standard usage of the debug print function requiring a comptime-known format string.

```zig
std.debug.print("{s}'s power is {d}\n", .{user.name, user.power});
```
Tokens:
Raw